Troubleshooting Ruby

Two places to look when a deploy misbehaves:

• Build log: the Deployments tab streams the full output from Ruby install, bundle install, and rake tasks. Every build error and every Bundler error surfaces here.
• Runtime log: the Logs tab streams stdout and stderr from your running pods. Startup crashes, unhandled exceptions, and native-load failures show up here.

This page lists the errors that come up most often, in the order they'd typically bite you: detection, Ruby install, bundler, rake, then runtime.

Common build errors#

Gemfile.lock not found#

The build looked for Gemfile.lock at the repo root and didn't find it. A Gemfile alone is not enough.

Fix. Commit Gemfile.lock alongside your Gemfile:

bundle install
git add Gemfile.lock
git commit -m "Add Gemfile.lock"

Make sure the lockfile isn't in your .gitignore. Some older Rails templates ignored it by default.

Error installing Ruby#

The Ruby version pinned in Gemfile.lock isn't in the Primcloud Runtime. Either the version isn't a real release, it's too old and no longer shipped, or the patch number typo'd (3.6.0 when you meant 3.0.6).

Fix. Bump to a version listed in Runtime versions:

ruby "3.4.10"

Then regenerate the lockfile:

bundle update --ruby

Error installing your application's dependencies#

bundle install failed. This is a broad bucket. The Bundler error above Primcloud's own message names the actual cause: a gem missing from the registry, a native extension that couldn't build, or a version conflict.

Fix. Reproduce locally with the same env the build uses:

BUNDLE_DEPLOYMENT=1 BUNDLE_FROZEN=1 BUNDLE_WITHOUT=development:test bundle install

If that succeeds locally but fails on Primcloud, the difference is usually native library dependencies (see the next entry) or an unresolved private-gem credential.

Native gem build fails (missing system library)#

Symptom: bundle install fails with output like:

An error occurred while installing pg (1.5.4)
Header files for the PostgreSQL client aren't installed.

Native gems (pg, mysql2, sqlite3, nokogiri when compiling from source, rmagick, sassc) need OS-level development headers to build.

Fix. Declare the required Debian packages in project.toml. See Customizing the build → Debian packages. Common pairings:

Precompiled binaries for most of these ship in newer gem versions. Bumping the gem is often a simpler fix than installing headers.

Frozen mode lockfile mismatch#

Symptom:

The dependencies in your gemfile changed, but the lockfile can't be updated because frozen mode is set

A gem was added, removed, or version-bumped in Gemfile without regenerating Gemfile.lock.

Fix.

bundle install
git add Gemfile.lock
git commit -m "Refresh lockfile"

Reproduce locally by running bundle install --frozen. You'll get the same error before ever pushing.

Error detecting rake tasks#

The build ran rake -P to enumerate tasks and it exited non-zero. This is usually because the Rakefile requires a gem that's only in the development or test group. Those groups are excluded by BUNDLE_WITHOUT=development:test, so the require fails at build time.

Fix. Move gems required by the top-level Rakefile (or files it loads unconditionally) out of the :development/:test groups. Wrap dev-only rake tasks in a begin/rescue LoadError block or only require dev gems from within task blocks:

task :lint do
  require "rubocop/rake_task"
  RuboCop::RakeTask.new
  Rake::Task["rubocop"].invoke
end

Error compiling assets#

rake assets:precompile failed. Common causes:

• Missing RAILS_MASTER_KEY. Newer Rails versions read encrypted credentials during asset precompile. Set RAILS_MASTER_KEY in the Secrets panel; see Deploying Rails → Env vars this framework expects.
• Missing Node/Yarn tooling. If asset compilation runs JavaScript build steps (esbuild, Rollup, Sass), commit a package.json and/or yarn.lock. Their presence installs Node.js so the JS toolchain is available. For a Bun-based pipeline, commit bun.lock beside package.json. See Ruby on Primcloud → Detection.
• App code raising at load time. Precompile boots the Rails app. Anything that raises during initialization (bad ENV fetch, missing credential) fails the task. The traceback is in the build log.

Fix. Address whichever cause the traceback points at. To reproduce locally with the same env:

RAILS_ENV=production SECRET_KEY_BASE=dummy bundle exec rake assets:precompile

Common runtime errors#

App doesn't bind to $PORT#

Symptom: the deployment reaches Release Succeeded but the URL returns a connection error, and the runtime log never shows a "listening on" line.

Fix. Make sure your web command reads $PORT. Primcloud's default Rails and Rack commands do this automatically. If you shipped a custom Procfile, bind explicitly:

web: bundle exec puma -C config/puma.rb -p $PORT

PG::ConnectionBad or database URL errors#

Symptom on Rails:

PG::ConnectionBad: could not translate host name "..." to address

The database URL is missing or points at an unreachable host.

Fix. Set DATABASE_URL in the Secrets panel to point at your PostgreSQL instance. Rails reads it automatically via config/database.yml when production.database_url isn't set.

Missing native library at runtime#

Symptom:

LoadError: cannot open shared object file: No such file or directory - libvips.so.42

Your app (or a gem) links against an OS library that isn't in the run image.

Fix. Declare it in project.toml; see Customizing the build → Debian packages. Add the package name to the install list and redeploy.

App exits immediately on start#

The runtime log shows the process starting and exiting with no other output.

Most common causes:

• Missing SECRET_KEY_BASE. Rails apps read it during boot. Primcloud sets a random default and caches it per-app, so a fresh app should not hit this, but if you overrode it and then unset it, Rails will refuse to start. Set it back in the Secrets panel.
• Missing RAILS_MASTER_KEY. Required to decrypt config/credentials.yml.enc when your app reads from encrypted credentials at boot.
• Startup exception before logging is configured. Wrap your app entrypoint in a rescue => e; STDERR.puts e.full_message; raise; end block, redeploy, and read the traceback from the runtime log.

Debugging tips#

• Reproduce locally with the same environment. Set RAILS_ENV=production, BUNDLE_DEPLOYMENT=1, BUNDLE_FROZEN=1, BUNDLE_WITHOUT=development:test, then run bundle install and your web command. Most build and boot failures reproduce this way.

• Check the resolved Ruby and Bundler versions in the build log. The build prints them near the top:

  Ruby version `3.4.10` from `Gemfile.lock`
  Bundler version `2.5.23` from `Gemfile.lock`
  

  Compare to what your Gemfile.lock says. A default source means Primcloud chose for you.

• Turn on Bundler verbose output temporarily. Set DEBUG=1 on the environment; Bundler logs additional detail during bundle install.

• Confirm gem loading with bundle list. Ship a one-time task that logs Bundler.load.specs.map(&:name) at boot to verify a suspected gem is actually installed in the release image.