Deploys and builds
Fix failed builds, unreachable apps, missing deploys, and full servers.
The build fails
Read the build log first. Use the last error line to choose the fix.
| In the log | Cause | Fix |
|---|---|---|
command not found | Detection chose the wrong command, or a dependency is missing | Set Build command in Settings -> Deployments, or add the dependency |
Cannot find module | The build ran in the wrong directory | Set Root Directory |
pull access denied | A private image with no matching credential | Add the registry in Settings -> Registries |
Authentication failed while cloning | The Git credential expired or was revoked | Settings -> Git, then Test connection |
no space left on device | The server's disk is full | See "No space left on device" below |
| The log ends with nothing | The builder was killed, usually for lack of memory | Raise the memory limit, or use a bigger build server |
Detection runs on every deploy. If it changed after a repository change, set the commands explicitly; explicit settings win.
The build passes but the app is unreachable
Check these in order:
- Container port: it must match the port your process listens on.
- Bind address: listen on
0.0.0.0, not127.0.0.1. - Container status: read the app's Logs if it exited.
- Domain state: only a routable domain can reach the app. See Domains and TLS.
Use the generated address (like https://deplo-cb00710a.deplo.site) to separate an app
problem from a DNS or certificate problem.
The app restarts, is unhealthy, or has no container
Open the app's Logs tab and look at the runtime notice:
- Restarting: the process starts and exits repeatedly. Check its command, required variables, and the last log lines.
- Unhealthy: the container is running but its healthcheck fails. Check the
path, port, command, and whether
curlorwgetexists in the image. - Degraded: a Compose service is missing or stopped. Check the service named in the notice and its logs.
- Not running: the app is deployed but no container is running. The logs usually show why it exited.
- Stopped after 10 restarts: restart loop protection stopped the container because it kept crashing. Fix what the logs show, then press Start. See Logs.
After changing variables, the healthcheck, or storage, Redeploy. Use Rebuild container only when the rendered stack must be recreated.
A push does not start a deploy
| Check | Where |
|---|---|
| Is Deploy on push on? | Settings -> Deployments |
| Is the webhook healthy? | Same page. A red state means the provider cannot reach this instance |
| Is it the branch the app tracks? | Deploy source |
| Do Watch paths exclude what you pushed? | Same page. Empty means deploy on anything |
| Is it a bare Git URL? | Then there is no webhook at all. Use the deploy hook |
If the panel address changed, update the webhook or use a new deploy hook.
A deploy is stuck in the queue
Deploys to one server run one at a time by default. Check the build log and the target server:
- Another deploy is running. Wait, or raise Concurrent deployments in the server's Overview.
- A build server is full. Check that server too.
- The target server is unreachable. Refresh its health.
No space left on device
Open Settings -> Servers -> the server -> Cleanup, then click Reclaim disk now. If little space is freed, check old app images and the build cache. Set a Schedule and review Images kept per app.
No automatic pruning
Deplo deliberately never runs system prune, container prune or volume
prune, because on a Deplo host a stopped app is a live app and a dangling
volume may hold somebody's data.
Watch the interaction with rollbacks
Keep Images kept per app at least as high as the app's Keep, or rollback targets can be pruned.
A rollback fails or is not offered
- Not offered: the source is a Docker image or Compose stack, or an uploaded archive past Keep. Deplo has no image or commit to go back to.
- Missing image: it was pruned. Raise Keep and Images kept per app.
- Agent too old: rebuilding an older commit needs a recent server agent. Update it from Settings -> Servers.
The deploy succeeded but the app did not change
- Variables and storage changes apply on the next deploy; saving alone does not deploy.
- If the rendered Compose stack is unchanged, use Rebuild container in Settings -> Advanced.
A deploy shows an old error after restart
After a control-plane restart, an in-flight deploy can show error even when
the containers are running. A later telemetry update clears that stale state.
Next steps
Did this page help you?