ZoophostDocs

Failed deployments

Read a failed build log, recognize the common causes, and fix them without guessing.

Troubleshooting3 min read

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

  1. Open the app → Deployments.
  2. Open the failed deployment.
  3. 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.json disagree. 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 .dockerignore and 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

  1. Push the fix (auto deploy picks it up), or
  2. 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
Talk to a human
Still stuck? Open a ticket from Support tickets in the console, or email [email protected]. Include the service name, the exact error and what you already tried.