Build & deploy failures

When a build fails, the project shows Failed with red status. Click the failed deploy → Logs to see what went wrong.

Reading the log output

Build logs stream three sections:

1. Setup — clone, runtime install, cache restore
2. Build — your build command's stdout/stderr
3. Run (only if build succeeded) — container startup output

The error is usually in section 2.

Common build failures

Error	Cause	Fix
npm ERR! 404	Private package without auth	Set NPM_TOKEN build env var
Cannot find module …	Missing dep	Add to package.json, push
Out of memory	Build heavier than tier	Upgrade tier or split build
EACCES permissions	Cache dir conflict	Open ticket, we'll clear it
Wrong Node/Python version	Detection picked wrong	Set in deploy.json buildEnv
Timeout	Build took too long	Cache more aggressively, or upgrade tier

Common runtime failures (container starts then exits)

• Wrong PORT — your app must listen on process.env.PORT. We pass PORT=<assigned>. Default 3000 only works if we happened to assign that.
• Database not ready — race condition between attached service startup and your app. Add a retry loop in your app's DB connection logic.
• Missing env vars — your code throws on startup if DATABASE_URL is undefined. Check Variables.
• Migrations failed — Rails/Django/Prisma migrations error at boot. Logs show the SQL error.

Restarting

After a config or env change, click Redeploy. Pushes the same commit through the pipeline again.

Rolling back

Deployments tab → pick a known-good past deploy → Promote. We swap the container without rebuilding (same image, restart with the previous env). Takes 5–10 seconds.

Logs after the build

/tools/deploy/<project> → Logs — streaming app logs (stdout + stderr). Search/filter built in. Persistence: 7 days of history.

For longer retention or structured logging, pipe to your own logger (Datadog, Logtail, etc.) — we don't lock you in.

Still stuck

Hit the chat. A real engineer will look at the logs with you. We don't bounce you to tier-1.