Failed deployments
Read a failed build log, recognize the common causes, and fix them without guessing.
A failed deployment leaves the previous release running. That is deliberate: a bad build should not take the site down. The job is to read the log and fix the cause.
Find the failure
- Open the app → Deployments.
- Open the failed deployment.
- Choose Logs.
The log streams while the build runs and stays available afterward. Copy puts it on the clipboard for a ticket.
Read from the bottom up. The last error is usually the cause; earlier lines are context.
Common causes
Missing or wrong start command
Error: Cannot find module '/app/server.js'
The build succeeded but the start command points at a file that does not exist. Check Settings → Build → Start command and the build pack's detection. For a monorepo, the file may be under a subdirectory — set Base directory.
Dependency install failure
npm ERR! code ERESOLVE
- A lockfile and
package.jsondisagree. Regenerate the lockfile locally and commit it. - A private package needs a token. Pass it as a build-time environment variable.
- A native module needs system libraries. Use a Dockerfile and install them explicitly.
Build command failure
Look for the first error above the stack trace. Common causes:
- TypeScript errors that fail a strict build
- A test or lint step wired into the build script
- An environment variable that is read at build time but was not set
- A generated file that is missing because it is gitignored
Reproduce locally with the same command and the same environment to confirm.
Out of memory
Killed
or a Node heap error. The build needs more memory than the plan provides. Options:
- Reduce parallelism (for example a lower worker count)
- Use a lighter build
- Move to a larger plan
- Build the image elsewhere and deploy it as a Docker image
Dockerfile errors
COPY failed: file not found— the build context does not include the file. Check.dockerignoreand the path.exec format error— the base image architecture does not match.- The container builds but exits immediately — the foreground command is wrong or the app cannot bind its port.
Wrong port or bind address
The build succeeds and the deployment fails health checks. The app must listen on 0.0.0.0 and the expected port. A server on 127.0.0.1 is unreachable from the proxy.
Environment variable missing at build time
Frontend frameworks inline public variables during the build. If a NEXT_PUBLIC_* or VITE_* value is missing, the build may succeed with a broken bundle. Confirm the variable exists and has Build enabled.
Monorepo path problems
The build runs from the repository root by default. Set Base directory to the app folder. If the app imports packages from elsewhere in the repo, the build context must still include them.
Cancel a stuck build
Cancel is available while a deployment is queued or building. Once it is deploying, let it finish or wait for the timeout.
A build stuck for a long time is usually waiting on a network fetch — an unavailable registry or a slow package download. Cancel, check the log's last line, and retry once.
Fix and redeploy
- Push the fix (auto deploy picks it up), or
- Choose Redeploy after changing settings or environment variables.
The previous release stays live until the new build succeeds, so you can iterate without downtime.
When it is not your code
Open a ticket with:
- App name and deployment ID
- The full build log, or the last 100 lines
- The commit SHA
- Whether the same commit built successfully before
If the log shows a platform-side error (registry, disk, network) rather than your build command, say so explicitly — it changes who investigates.
Next
- build failed
- deploy failed
- logs
- exit code
- npm
- dockerfile
- monorepo
Ready to use this
If the guide did not fix it, tell us what you already tried.
- A real support thread, not a bot loop
- Support in IST

