Troubleshooting failed deploys
What each failure on the deploy page means and how to fix it.
A failed deploy shows Why it failed at the top of its page: the cause, the fix and the log line that proves it. Each cause is explained here.
The build ran out of time
The build was stopped at its time limit (60 minutes). The next attempt reuses what was already built. If it keeps happening, the build needs more memory or CPU — see build methods.
The build ran out of memory
A build step was killed for using more memory than the build server has. Railyard already tunes builds to the machine (swap, Node heap, one job at a time on small servers). A larger build server, or deploying the project’s published image, avoids it.
The app started but never answered
The container is running but nothing answered HTTP. The app must listen on 0.0.0.0 and on the port in $PORT. Check the port under Settings, and that the start command doesn’t bind to 127.0.0.1.
A dependency is missing at runtime
The code needs a package that isn’t in the image — usually the wrong framework was detected or the command runs outside the app folder. Check the build method and start command.
The command ran in the wrong folder
The image doesn’t contain the app where the command expected it. If the repo’s Dockerfile is only for development, build with Railpack instead.
The app needs credentials for an outside service
It calls a third-party service (cloud storage, email, payments…) and has no key for it. Add that service’s variables under Variables.
The database user lacks a permission
A migration needs a permission the app’s database user doesn’t have. Redeploy once — grants are refreshed on every deploy.
The database wasn't reachable
The app couldn’t reach its database. If this happened during the build, the app connects to its database while compiling, which builds can’t do.
A required variable isn't set
The app stops at boot because a variable it needs is empty. Add it under Variables.
The image couldn't be pulled
The registry refused the image: it doesn’t exist, the tag is wrong, or it’s private and needs credentials under Settings → Source.
The image name is invalid
The image reference contains characters Docker doesn’t accept. Check the repository URL or image name.
The release step failed
The command that runs before the new version goes live — usually migrations — exited with an error. The first error line is shown on the deploy page.
The build failed
A build step exited with an error; the first error line is shown on the deploy page.