Troubleshooting Apps

Symptoms you can hit when creating, deploying and running an app, with their cause and fix.

Last updated 18 November 2026View as Markdown

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.

Did this page help you?