Build failed

Where to look first

Open the failed deployment and read the Build logs panel bottom-up. Nixpacks prints a clear cause for most failures.

Common causes

Missing or unexpected runtime

• Symptom: Could not detect a builder for this app.
• Fix: Commit a runtime manifest (package.json, pyproject.toml, go.mod, etc.) to the repository root.

Wrong version pin

• Symptom: Node.js 14 is no longer supported.
• Fix: Pin a supported version using your runtime’s native mechanism, e.g. "engines": { "node": "20.x" } in package.json.

Failing install step

• Symptom: npm ci or pip install fails.
• Fix: Reproduce locally with the same versions. Common culprits: private dependencies requiring auth, unpinned transitive dependencies breaking.

Build hangs without completing

• Symptom: Build never finishes; the deployment row stays in building past what feels reasonable.
• Fix: No hard build timeout is enforced today (Phase 5 hardening will add one). If a build is stuck, cancel it by re-pushing a new commit (the worker switches to the latest deployment). Common causes: large npm install chains, native build steps without prebuilt binaries, network issues fetching dependencies. Reduce work at build time (cache prebuilt native deps in your repo or vendor them) or contact support.

If none of the above matches

Copy the last ~20 lines of the build log and open a support ticket with the deployment URL.