Ship changes with a repeatable path.

Find the failing layer

Here is the process broken into clear steps. Take them one at a time and check each off before continuing.

1. Read the first meaningful build error, not only the final summary.
2. Check dependency versions and TypeScript errors.
3. Confirm every required environment variable exists in the target environment.
4. Test the route directly on the published domain.
5. Check case-sensitive paths, asset imports and client-side fallback routing.
6. Validate the production bundle with the same configuration used to deploy.

While working through those layers, keep these common traps in mind.

• A local dev server can hide missing production variables.
• A route that works after navigation may fail on direct refresh.
• A successful build does not prove forms, auth or webhooks work live.

Release checklist

Here are the key things to get right. None of them are complicated on their own, but skipping one tends to undermine the rest.

• Build completes cleanly from a fresh checkout, not only a cached one.
• All environment variables are set in the production environment, not only locally.
• Direct navigation to every route works after a hard refresh.
• Forms, auth and webhooks are retested on the published domain, not preview.
• A rollback path exists if the release needs to be reverted quickly.

Diagnostic sequence for a failed deployment

Follow the sequence below from start to finish. The order matters: later steps assume the earlier ones are done.

1. Reproduce the failure from a clean build locally.
2. Compare environment variables between local and production.
3. Isolate whether the failure is build-time or runtime.
4. Check platform status and recent configuration changes.
5. Roll back if the cause cannot be identified quickly.