Deploys and builds
Fix failed builds, unreachable apps, missing deploys, and full servers.
The build fails
Read the last error line of the build log: for a Railpack build it usually names the fix. The build fields are on the Build card in Settings -> Deployments, the commands and Node.js version under its Advanced.
| In the log | Fix |
|---|---|
No start command detected | Set Start command |
Railpack does not recognise this folder | Set Root directory on the Source card, or add a Dockerfile |
is not available | Pin a released version: Node.js version for Node, the variable the error names (like RAILPACK_PYTHON_VERSION) for the others |
The code needs Node 22 and the build used Node 20 | Pick a Node.js version in that range |
A native module failed to compile under Node 24 | Set Node.js version to 22 |
The build needed more than 2.9 GB of memory | A build step went past 75% of the server's memory. Build on a bigger build server |
GitHub refused a download with its rate limit | Connect the GitHub App to the team, or deploy again in an hour |
The repository's lockfile does not match its package.json | Commit an updated lockfile, or set Install command |
command not found or Cannot find module | Set Build command or Root directory, or add the missing dependency |
pull access denied | Add the registry in Settings -> Registries |
Authentication failed while cloning | Settings -> Git, then Test connection |
no space left on device | See No space left on device |
Detection runs on every deploy, and an explicit setting always wins over it.
The build passes but the deploy fails
After the build, Deplo waits up to 3 minutes for the app to start and stay up. The log says what went wrong, then prints the app's last lines.
| In the log | Fix |
|---|---|
keeps restarting or stopped right after it started | The app crashes on start. Its last lines say why: usually a missing variable or a database it cannot reach |
The start command runs a program that is not in the image | Fix Start command |
listens only on 127.0.0.1 | Make the app listen on 0.0.0.0 |
never listened on port 3000 | It opened no port: check that it starts a web server. A worker with no domain only has to stay up |
was stopped: out of memory | Give it more memory in Resource limits |
health check fails | Check the health check path and port |
A wrong port is not on this list: Deplo routes to the port the app really listens on and says so in the log. See the port.
The build passes but the app is unreachable
- The generated address works? Then it is the domain: see Domains and TLS.
- The Logs tab shows a notice? See below.
- A port set on one domain row must be one the app listens on.
The app restarts, is unhealthy, or has no container
The app's Logs tab shows a notice above the output:
| Notice | Fix |
|---|---|
This container is in a restart loop | It starts and dies. The error is in the output below |
This container is running but failing its healthcheck | Check the path, the port, and that curl or wget exists in the image |
This container is not running | Read what it printed before it stopped |
Only 2 of 3 containers are running | Pick the stopped one in the toolbar's container picker |
web has no container on the host | Redeploy the app |
Deplo stopped this container after 10 restarts | Restart loop protection stopped it after 10 crashes in 30 minutes. Fix the error, then press Start |
After changing variables, the health check or storage, Redeploy. Use Rebuild container (Settings -> Advanced) only when the stack itself must be recreated.
A push does not start a deploy
| Check | Where |
|---|---|
| Deploy on push is on | Releases card in Settings -> Deployments |
| The push is on the branch the app tracks | Source card, same page |
| Watch paths do not exclude it. Empty means everything | Releases -> Trigger |
No Deplo could not add the push webhook warning | Source card. Add the webhook by hand with the URL it shows |
| It is not a bare Git URL with no Git connection | That has no webhook at all: use the deploy hook |
Moved the panel's address? Webhooks and deploy hooks still point at the old one.
A deploy is stuck in the queue
- Another deploy runs on that server. Wait, or raise Concurrent deployments (1 by default) on the server's Overview tab.
- A build server is busy. Check it too.
- The server is offline. See Servers and agents.
No space left on device
Settings -> Servers -> the server -> Cleanup -> Reclaim disk now, then set a Scheduled cleanup. Each app keeps the images its Rollbacks kept needs; Images kept per app covers the apps that cannot roll back.
No container or named volume is ever removed
Cleanup never runs system prune, container prune or volume prune: on a Deplo host a stopped app is
still an app, and a named volume may hold somebody's data.
A rollback fails or is not offered
| Message | Cause |
|---|---|
This app doesn't build an image Deplo can re-run | Only apps deployed from a repository or an uploaded archive roll back |
This deployment's image is no longer kept on the server | Raise Rollbacks kept in Settings -> Deployments |
This deployment ran on another server | Only builds from the app's current server can be rolled back to |
this server's agent is too old to build a specific commit | Update the server agent from Settings -> Servers |
The deploy succeeded but the app did not change
- Variables and storage apply on the next deploy: saving alone does not deploy.
- If the rendered stack is unchanged, use Rebuild container in Settings -> Advanced.
Next steps
Did this page help you?