Match your symptom to the section below. Almost every deploy failure falls into one of three buckets: the build never produced an image, the release task exited non-zero, or the new container never passed healthchecks.
The build never produced an image
Symptom
What to do
Failure during app build with no clear cause
Read the build log carefully — the buildpack always prints a final stack trace before this line. ownstack remote deploy-log.
Node.js vX.Y.Z is not supported (or similar version refusal)
The buildpack picked a Node version your dependency rejects. Pin "engines": { "node": ">=22.12.0" } in package.json.
Could not detect default buildpack
Buildpack auto-detect failed. Add a recognized file (package.json, Gemfile, etc.) or set BUILDPACK_URL explicitly.
error: failed to push some refs to '...:<app>' with no other context
Pre-receive hook declined. Look upward in the log — the actual error is on a remote: ... line earlier.
Build runs out of memory
Increase the stack instance size, or pre-build the image in CI and use image deploys.
The release task exited non-zero
The release task is whatever is in release: in your Procfile. Most commonly it's db:migrate. Failures here keep the previous container serving — but no traffic moves to the new code.
Symptom
What to do
PG::ConnectionBad: FATAL: password authentication failed for user "postgres"
Almost always password drift after a database import. Repair after import — one ALTER ROLE fixes it.
PG::ConnectionBad: connection refused
Postgres service is stopped or unhealthy. ssh dokku@<stack-ip> postgres:status <svc> to check; postgres:start <svc> to revive.
ActiveRecord::PendingMigrationError
You skipped db:migrate but still need it. Add it to the release Procfile entry.
migration X failed: ...
Application bug in the migration itself. Fix the migration, redeploy.
bundle: command not found on dokku-induced restart
Buildpack PATH not set in the restart context. Often shows up after postgres:unlink. ownstack remote restart via the control plane (which uses ps:rebuild) usually clears it.
Healthcheck failed
Symptom
What to do
port listening check: unable to enter the container
Web process didn't bind to $PORT. Confirm your start command uses $PORT (not a hardcoded port).
container has restarted N times
Process crashing on startup. ownstack remote logs --tail 200 for the stack trace.
tini: exec bin/rails failed: No such file or directory
Image is missing the binary the entrypoint expects. Common after a buildpack switch or a partial restart cycle. Trigger a clean rebuild: ssh dokku@<stack-ip> ps:rebuild <app>.
Healthcheck times out
App is slow to start. Add an uptime check with a longer wait in app.json. See Healthchecks.
Push-side errors
Symptom
What to do
Name is already taken
Harmless. Dokku is saying the app already exists. Deploy continues.
Unable to remove deploy lock
A previous deploy crashed mid-flight. ownstack app unlock <app> clears it.
fatal: could not read Username for 'https://github.com'
Submodule auth on the control plane. Check that the control plane has access to private submodule repos.
If you really can't tell what went wrong
Read the entire log from ownstack remote deploy-log --deployment=ID. The cause is in there; CLI summary truncates aggressively.
Try a known-good SHA via ownstack deploy with a previous commit. If that succeeds, the issue is in your changes.
Reproduce locally with ownstack local stack start and a local stack target. Same buildpack, same release task, just on your machine.
Open a doc issue describing the symptom — concrete error messages help us improve this page.