Troubleshooting Apps
Symptoms you can hit when creating, deploying and running an app, with their cause and fix.
The create form rejects the compose file with a line number
Cause: a key or value the platform cannot honour. Fix: the message names the key and why; change the file. See Compose files.
Deployment failed: "Deployment did not become healthy in time"
Cause: the app's machines did not report the new generation healthy within 8 minutes (20 when
the deployment created a new machine). The rollout lines above the message carry what the machine
reported. Fix: check the container's logs on the Logs tab; check the port; set
healthCheck to the path your app answers. See
Configure the release command and health checks.
Deployment failed: "… health check: GET /… answered 404, expected 200"
In CI, dcloud deploy apps deploy --wait exits 6 with this message. Cause: the health check
sets expectedStatus 200 and its path does not exist in the app. Without expectedStatus, any
status below 500 counts as healthy. Fix: set healthCheck.path to a route the app serves, or
remove expectedStatus.
Deployment failed: "Release command exited with code N; the previous version keeps serving."
In CI, exit 6. Cause: the release command failed; its last lines follow the message. Code 124 means it did not finish within its timeout and was stopped. Fix: read the release output in the activity feed (in CI, the lines above the error). The previous version is still serving.
The activity repeats "Rollout attempt failed, retrying: pull …"
Cause: the image is in a private registry and the app has no credential for it, so it is pulled anonymously and refused. Fix: add a registry credential for that host; see Pull from another registry.
The activity repeats "Rollout attempt failed, retrying: registry login to ghcr.io …"
Cause: the stored credential was refused; the machine retries until the deployment times out. Fix: rotate the secret, or check the username, then deploy again.
Deployment failed: "App "…" pulls from registry repository "…", but this deployment names "…""
Cause: an app takes its images from one repository of your organization's registry, and this
image is in another. Fix: deploy an image from the app's repository, or create a separate app.
The related failures No repository called "…" in this organization's registry and
Tag "…" does not exist in registry repository "…" mean the image was not pushed: push it first.
Certificate pending, and DNS shows "No record" or "Points somewhere else"
Cause: the record is missing or points elsewhere. Fix: create the record the Domains tab shows; the machine requests the certificate once DNS resolves to it. See Add a custom domain.
A service's environment variable is empty
Cause: the variable is not named under that service's environment:, and the service does not
run the published service's image. Fix: add the bare name; see
Compose files.
A job run failed with exit code 127
The run's error reads "command or /bin/sh not found in the image". Cause: the command, or
/bin/sh, is not in the image. Fix: use the image's own path to the program. An image without
/bin/sh, such as a distroless one, cannot run jobs.
A job never runs
Cause: the app has not been deployed, or no machine has reported in; the Scheduled jobs tab then reads "Jobs start running once the app has been deployed and its machine reports in." Fix: deploy the app. Once a machine reports, the tab says which machine runs the jobs.
Data disappeared after replacing the machine
Cause: named volumes live on the machine's disk. Fix: back the data up before destroying a machine; a redeploy alone does not touch it.
Exit 4 on dcloud deploy apps deploy <slug>
Cause: resolving a slug lists apps. Fix: pass the app id, or allow deploy:DescribeApp on
rn:ews:de1:<organization id>:deploy:*.
docker push answers denied
Cause: the key lacks ecr:PushImage on the repository, or the repository does not exist.
Fix: create the repository, or add the permission.
Exit 7
Cause: the rollout takes longer than --timeout (a first deployment installs the machine).
Fix: raise --timeout; the deployment keeps going and its result is on the app page.
Pushes do not deploy the app
Cause: deploy on push is off (apps created before 2026-11-17 have it off), or the person who
pushed lacks deploy:DeployApp; the app's activity says which. Fix: see
Turn on deploy on push.
A rollback answers 409
Cause: you asked to restore the environment ("restoreEnvironment": true) of a deployment made
before environments were recorded ("Generation N predates recorded environments, so it cannot be
restored"), or a secret that deployment bound has been deleted since ("The secret bound to KEY in
that deployment no longer exists"). Without restoreEnvironment, a rollback to an unrecorded
deployment runs its image with the current environment. Fix: roll back with the current
environment ("restoreEnvironment": false), or bind a secret to the variable under Environment.