Docs
Troubleshooting
The failures we see most, and exactly what fixes them.
Start with the diagnosis card on the failed deployment — the Build Doctor names the root cause for virtually every failure. This page covers the patterns behind those cards.
Build failures
| Symptom | Cause → fix |
|---|---|
Cannot find module X | Dependency missing from package.json (phantom dep), or tooling in devDependencies your build imports. Declare the dependency; monorepo phantom imports are tolerated in pnpm builds via hoisting, but declaring is correct. |
| Node version errors (EBADENGINE) | Set engines.node in package.json (majors only, e.g. "20.x") — detection honors it. |
| Lockfile out of sync | Commit an updated lockfile (pnpm install locally, commit pnpm-lock.yaml). Builds try a strict install first and fall back once, but the warning means drift. |
npm can't install workspace:* | A workspace repo built with the wrong manager — commit the root lockfile of the manager you actually use. |
Prisma: @prisma/client missing | Generation runs automatically when a schema exists; if you moved the schema, point prisma.schema in package.json at it. |
Crashing containers
| Symptom | Cause → fix |
|---|---|
| Ready in logs, then killed (SIGTERM) | The app listens on a different port than detected or on localhost. Listen on 0.0.0.0; if your start command names a port (--port 3002) the platform follows it automatically. |
| Crash only in production | Almost always a missing environment variable — check the runtime logs on the deployment page, then add the variable and redeploy. |
EACCES writing files at boot | Containers run as a non-root user. Write to /tmp (writable) instead of the app directory; caches are pre-pointed there. |
| Background worker keeps restarting | Make sure the app's type is Worker — web-type apps get port health checks that a non-listening process fails. |
Domains & TLS
- Verification never passes: on Cloudflare use DNS-only (grey cloud); confirm the CNAME targets
cname.buildfyio.comor the A record targets the platform IP. Automatic re-checks stop after ~1 hour — use Check now. - SSL error right after verifying: issuance takes a few seconds after the first successful route; hard-refresh. Status is live in the Domains section.
- Domain already in use: hostnames are globally unique — remove it from the other project first.
Still stuck?
Every failure surfaces its reason on the deployment page — nothing sits silently in queued. If a diagnosis card seems wrong or missing, contact support with the deployment ID; the full build log is attached to it.