Troubleshooting · Build
Deployment failed? Start with the log.
A Runex deployment fails either during the build or when the app starts. The deploy's log in the dashboard tells you which, and usually the exact line to fix. Your previous version keeps serving traffic meanwhile.
- Build or start?
- Log shows the line
- Production stays up
npm ci npm ERR! Could not resolve dependency # lockfile out of sync with package.json deploy failed at build traffic still on #127 (healthy)
Diagnose
Did it fail during the build or at start?
The stage tells you where to look.
| Build failure | Start failure | |
|---|---|---|
| When | Installing or compiling | After the build, when the process starts |
| Typical cause | Dependencies, versions, syntax | Missing env variables, wrong port, crash |
| Where to look | Build log | Runtime log |
Build
How do you fix a failed build?
Four causes cover most build failures. Missing values are a top cause, so double-check your environment variables.
- Lockfile out of sync: run the install locally and commit the updated lockfile
- Wrong runtime version: set the Node, Python, or Go version your code needs
- Missing build dependency: move it from devDependencies if production builds need it
- Dockerfile error: build it locally with docker build . to reproduce
Start
How do you fix an app that crashes on start?
Check variables, port, and the start command. A server bound to localhost is the classic cause; the port configuration guide shows the fix.
- A required environment variable is missing: the runtime log usually names it
- The app listens on the wrong port or on localhost
- The start command exits immediately instead of running a server
- The app can't reach its database: check DATABASE_URL
FAQ
Failed deploy questions
Quick answers while you debug.
Why does my build pass locally but fail on Runex?
Usually a lockfile or runtime-version difference, or a file that exists on your machine but isn't committed. Build from a clean clone to reproduce.
Is my site down when a deploy fails?
No. Runex only switches traffic after a new deploy passes its health check, so the previous version keeps serving.
How do I retry a failed deploy?
Push a fix to the branch, or redeploy the same commit from the dashboard if the failure was temporary. If the last version was fine, an instant rollback restores it while you fix the issue.