Troubleshooting#
Symptom-led recovery, fastest check first.
Start here#
Run the full verification. It reproduces most reported problems locally, because it builds and exercises the real artefact:
npm testIf that passes and production still misbehaves, the problem is in the deployment or in DNS rather than in the source.
Build and dependency problems#
| Symptom | Check | Recovery |
|---|---|---|
npm install fails on an engine check |
node --version |
Install Node 22.13.0 or newer |
| Build fails with a type error | The build output — it names the file and line | Fix the type; the assertions never ran |
| Build succeeds locally, fails on the platform | The builder's Node version | Align it with the engines requirement |
| Development server has no hot reload | Whether native filesystem events are available | Force polling by setting CODEX_SANDBOX=seatbelt, or restart the server |
Failing assertions#
| Symptom | Check | Recovery |
|---|---|---|
| A copy assertion fails | Whether you edited that section | Restore the claim, or change copy and assertion together |
| A retired-claim assertion fails | Whether a withdrawn claim came back | Remove it — see Editing page content |
| The structured-data assertion fails | Whether the JSON-LD block still exists | Restore the block; edit its contents instead of removing it |
| A header assertion fails | Whether the worker still sets that header | See Response headers |
| The redirect assertion fails | The hostname comparison | See Domains and redirects |
Production problems#
| Symptom | Check | Recovery |
|---|---|---|
| Deployment never becomes healthy | Deploy logs for an error rendering / |
The health check requests /; fix the route and redeploy |
| Stale content after deploying | Request with curl rather than a browser |
Confirm the deployment promoted, then redeploy |
| Headers present locally, absent in production | Whether a static response is served ahead of the worker | Confirm the deployment is current and the platform is not intercepting |
www no longer redirects |
The response status and Location for the www hostname |
See Domains and redirects |
| Social preview letterboxed or blank | Whether the shipped image matches its declared dimensions | Update image and declared dimensions together |
A blocked asset#
An external image, font, script or stylesheet will be blocked by the Content
Security Policy. The policy allows same-origin resources, data: images, and
form submissions to GitHub.
Self-host the asset. Widening the policy is a security decision and should not be made to unblock a content change. See Response headers.
Preserve evidence before you retry#
If a deployment failed and you are about to redeploy, capture the build and deploy logs first. Redeploying replaces them, and an intermittent failure is much harder to diagnose from a second, cleaner run.