How to debug a 404 that only happens after deploy

A 404 that only happens after deploy should be debugged by separating route generation, asset version, server rewrite rules, and cached links.

The first mistake is checking only the local route. Local development often has a fallback server that accepts every path, while production may require a rewrite rule, static export file, route manifest, or CDN configuration. A link that works locally can fail in production if the generated path is missing, the base path changed, the trailing slash rule differs, or an older HTML file points to a new route that was not deployed with it.

Start with the exact URL that fails. Open it directly in a clean browser session, then request it with headers that show whether the response came from the app server, CDN, static host, or reverse proxy. Compare the production route list or build output with the link that generated the URL. If the route uses dynamic parameters, check whether the slug was encoded differently after deploy.

Next, check deployment timing. A CDN can serve old HTML with new JavaScript or new HTML with old assets. That mismatch can create links to routes that do not exist in the current edge cache. Purging cache may hide the symptom, but the note should still record which layer served the stale response.

The useful fix depends on the layer. A missing static file needs build configuration. A direct deep link needs a rewrite. A stale link needs cache invalidation. A bad slug needs route encoding. Treating all deploy-only 404s as “routing bugs” makes the next failure harder to diagnose.

How to debug a 404 that only happens after deploy

// COMMENTS

ON THIS PAGE