page:guides:next js:deployment diagnostics

Diagnose deployment failures for Next.js

Summary

Diagnose a failed Next.js deployment on Ample. Deploy is synchronous: a failed next build returns build_failed with the deployment id, and ample logs expose the build log and then the runtime log so the cause is read, not guessed.

Prerequisites

• A deployment id from a failed ample deploy
• An Ample account token with servers:read

Workflow Steps

1. Read the failure code
   Exit 1 with build_failed means next build failed in the isolated builder; exit 2 means a required preflight action is blocking.
2. Read the build log
   Type errors, missing modules and memory failures show at the end of the build log.
   ample logs --kind build
3. Read the runtime log
   A live app that does not answer usually failed to bind 0.0.0.0 on PORT; the runtime log shows it.
   ample logs --kind runtime
4. Fix and redeploy once
   Change the source, then run ample deploy again. Do not loop deploys to poll status.

Examples

• Intentional build failure canary
  A failing build command is rejected synchronously and its stderr line appears in the build log.

Success Checks

• Manual
  Build log contains the failing command output:
  ample logs --kind build shows the failure line

Limitations

• Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
• Region, compliance attestations and request-duration limits are unknown and not claimed.
• Apps auto-pause when idle and wake on the next request; always-on is an operator setting, not a plan feature.
• Documentation only; no tool is executed automatically by the catalog.
• The failing-build evidence uses a generic Node fixture; Next.js-specific build failures were not separately reproduced.