HTTP 404 troubleshooting

What it means

An HTTP 404 means the responding server did not find a current representation for the target resource, or is unwilling to disclose that one exists. It does not by itself prove permanent deletion, a failed deployment or a particular broken layer. Diagnose the exact request, identify the component that answered, and compare its active routes or files with the intended result. DNS and TLS failures are different symptoms: do not label a request that never produced an HTTP response “404.” HTTP status semantics

Try it

Simulation — collect observations before choosing a correction. Start with the path-case case, inspect request details and the active-release inventory, then select the explanation supported by those observations. Apply the scoped correction and inspect the original problem path, a known-good control and a genuinely absent path. Other cases cover a missing exported file, incorrect proxy routing, a cached 404 and a method-specific handler defect.

The lab never fetches a URL or uploads logs. Its headers, files and routing evidence are prepared examples. An unsupported diagnosis produces a STOP message without changing the scene. Back first removes a local correction, then the most recent observation. Reset restores the first case and clears every observation, hypothesis, request choice, error and correction.

Without JavaScript, the initial example remains readable: GET /Docs/ receives 404 while the active example deployment has /docs/index.html. No cause has yet been established from the response alone.

Record the request before touching configuration

Work in an environment you are authorized to inspect. Capture the hostname, method, exact path, relevant query parameters, time, response status and redirect chain. Preserve case and encoding. Compare the failing navigation with a known-good request on the same service. Do not assume that a screenshot of the error text captures the request that produced it.

Use the browser's network inspection or an approved read-only HTTP client. Inspect status and headers rather than relying on a page's appearance: an error-looking document can be served with a success status, and a body-less response is not necessarily an error. Keep TLS verification enabled and bound diagnostic requests to the authorized target. Never paste authentication cookies, tokens or private response content into a public report.

HEAD is useful for inspecting metadata without a response body, but it is a different method from GET. HTTP defines HEAD in relation to GET with no response content; a faulty or specially configured handler can nonetheless produce a method-specific symptom. The lab deliberately includes such a faulty example. A passing GET test does not establish that the previously failing HEAD request now works. GET and HEAD · curl method and header options

Distinguish observations from hypotheses

These are diagnostic branches, not conclusions from a status code. Headers can provide clues, but a header naming a server does not conclusively identify every component involved. Combine observations that distinguish the plausible explanations. If an observation conflicts with your hypothesis, retain the conflict rather than selecting a convenient label.

Inspect the active deployment, not just the source tree

A local Markdown file or application route can exist while the deployed artifact is missing it. Establish which release is active, which root the file server uses, and whether the generated output contains the expected path. A build directory in another work folder is not proof that the live service serves it.

Also check how the server maps public URLs to files. A directory index, filename extension or canonical-slash rule can affect the request's path through the configuration. Follow the documentation for the actual serving software; do not assume a file server and an application router use identical rules. Caddy's file-server documentation, for example, describes joining the request path to a configured root and its handling of canonical URIs. File-server behavior

If the active export is incomplete, build and verify a complete candidate from the intended source, then use the normal controlled release process. Do not patch the active web root one file at a time: the HTML, assets, search index and route set may otherwise describe different revisions. Preserve the previous working release for a scoped rollback.

Separate edge, proxy and origin

The publicly observed response may come from a CDN, reverse proxy or application rather than the file server you first inspected. Determine which route matched and which upstream received the resulting method, host and path. A route inventory showing that the API supports a path is insufficient if the proxy actually forwards that path to a static upstream.

In the proxy preset, the synthetic trace makes this distinction explicit: /api/help/ is sent to the wrong upstream, which returns 404, while the intended API responds successfully. The minimal correction changes that mapping, not every route in the configuration. A real change needs the serving software's configuration validation and the existing deployment/rollback process. Reverse proxy behavior

For direct-origin diagnostics, use an approved method that preserves the intended hostname and security checks. A bare IP request may select a different virtual host or fail certificate verification, creating a new problem instead of isolating the original one. Do not disable verification or open an unprotected origin just to make a diagnostic command succeed.

Could the 404 be cached?

Some 404 responses can be cached, subject to HTTP cache rules. A repaired origin can therefore coexist with a stored edge response. Inspect applicable Cache-Control information, Age, redirects and any documented cache-status fields, then compare an authorized origin observation for the same request. One header without that context is not a diagnosis. HTTP caching · 404 cacheability

The cached preset supplies both parts of the evidence: the origin returns 200 while the edge supplies a prepared 404 with Age: 40 and Cache-Control: max-age=120. The local correction expires that exact stored response after the origin fix. It does not claim that clearing a browser cache purges a CDN or that a wildcard purge is always appropriate.

If you cannot determine which cache holds the response or whether its policy permits the intended action, stop and use the provider's documented procedure. Repeatedly purging unrelated content can conceal the evidence without repairing a wrong route or an incomplete deployment.

Make one justified correction

Choose the narrowest change that addresses the supported cause. Correct a bad referring link, restore a missing resource through a complete release, repair one proxy mapping, or fix the method-specific handler. An intentional redirect is another option when a particular old path has a legitimate replacement. Do not invent a redirect destination for an unrelated missing resource.

For the lab's case-mismatch scenario, the declared policy is to preserve the old /Docs/ link with one exact 308 redirect to /docs/, then serve the intended resource. The example keeps the method when following that redirect. In real work, decide whether a redirect is appropriate; correcting the referring link alone can be enough when the old URL should remain absent. 308 semantics and verified clarification

Do not redirect all missing paths to the homepage with 200, recursively loosen permissions with chmod 777, disable TLS checks or rewrite the whole routing configuration just to remove an error screen. Those are broad changes with different risks, not evidence-based 404 fixes.

Verify the correction and preserve rollback

Re-test the exact previously failing method, hostname and path. If the intended repair is a redirect, inspect its destination and final response as well as the first status. Test a known-good route to catch a regression, and a deliberately absent route to confirm that missing resources still receive an appropriate 404. Check the edge and origin separately when caching was involved.

Stop if the failing path remains unexplained, a control route changes unexpectedly, a redirect loops or the proposed fix requires changes outside your authority. Revert the scoped configuration or switch back to the retained complete release through the normal process. A local Back or Reset button only reverses the simulation; it is not a server rollback.

In practice

Keep a short evidence record: exact request, responding layer, active artifact, distinguishing observations, minimal correction and verification results. A 404 is the start of the investigation, not its conclusion. The goal is to serve the intended resource correctly while retaining honest failure behavior for resources that genuinely do not exist.