# 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](compose-files.md).

## 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](configure-release-and-health-checks.md).

## 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](pull-from-another-registry.md).

## 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](add-a-custom-domain.md).

## 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](compose-files.md#the-environment-of-each-service).

## 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](turn-on-deploy-on-push.md).

## 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**.
