HTTP 404 troubleshooting

What it means

HTTP `404 Not Found` means the server did not find a current representation for the requested target, or is not willing to disclose that it exists. It is an HTTP response, not a DNS error or a failed TLS handshake. A missing route, absent exported file, incorrect public root, pathname mismatch or reverse-proxy rule can all produce the same visible status. 404 semantics

Before editing production files or changing DNS, find which layer returned the 404. The public edge, reverse proxy and origin may have different routing tables or versions.

Try it

Example — compare a working route and a missing one. The table is fictional and uses documentation-only hostnames.

A read-only CLI check on an authorized public URL may use the following pattern. Substitute your own approved hostname; this is not an instruction to probe third-party infrastructure.

curl --head https://www.example.com/guide/

--head sends an HTTP HEAD request, which may be handled differently from GET; to confirm the browser's symptom, compare an ordinary browser GET too. Check the final destination after redirects, and do not post credentials or cookies in tickets. Method semantics

Diagnosis, from least risky to most specific

1. Record the full URL, request method, observed HTTP status, time and public hostname. Check wrong capitalization, encoding, slash and redirects. Keep any private query values out of shared logs.
2. Verify the new or old route exists in the deployed release, not merely in your local source tree. With a statically exported site, /learn/topic/ often corresponds to generated learn/topic/index.html; behavior depends on the site's configured static serving rules. A source Markdown file alone proves nothing about the active output.
3. Confirm the web server's document root and route rules through read-only inspection available to the authorized operator. Avoid changing symlinks, web roots or permissions as the first diagnostic step.
4. If traffic passes through a reverse proxy/CDN, compare which layer supplied the response. A proxy matcher may send the request to the wrong upstream, or a cached 404 may outlive an origin fix. Proxy routing
5. If an application generates pages dynamically, check its router and application logs for the exact target; do not assume the filesystem is responsible.

Minimal fix and verification

Correct the actual mismatch using the site's normal reviewed deployment process: restore the missing route in a new complete build, fix an approved proxy matcher, or correct an intended link. Do not copy individual Next.js HTML/JS files into a live release, loosen filesystem permissions globally, or delete old releases just to conceal the symptom.

Request both the previously failing URL and a nearby known-good URL after the change. Test direct navigation, reload, redirects and the true missing-route 404. Verify the intended canonical route and that no unrelated pages disappear.

In practice

A 404 tells you that the server responded; it does not prove why. For proxy connectivity and upstream failures instead, see HTTP 502 troubleshooting. For the message anatomy use HTTP request and response, and for static build behavior use Static vs dynamic website.