Caching behavior for errors and 404 pages

An error page can look like a complete HTML document. Storing it under a valid route would turn a temporary failure into a durable response, so POM Cache applies error and status guards during generation.

One shared 404 page per site

With HTML caching enabled, POM Cache automatically keeps one static HTML document for the site's public 404 page. Every missing URL shares that document; missing paths never create individual page-cache files.

WordPress still loads, resolves the requested URL, and runs normal redirect handling. Only after WordPress identifies a 404 does POM Cache reuse the document instead of rendering the theme again. The response remains HTTP 404, with no-cache headers. A URL that is later published can load normally without deleting the shared document.

On the first eligible GET, POM Cache makes one anonymous request to a fixed missing URL on the same site. This generates the theme's 404 without copying the original visitor's path, query parameters, cookies, or credentials. The request must complete as a public HTML 404. If generation fails, normal dynamic rendering continues. Concurrent requests do not launch duplicate generation requests, and failed generation is retried at most once per minute. HEAD requests can reuse an existing document but do not generate one.

The shared document has no age-based expiry. It survives the administration-bar Delete Cache, ordinary HTML/JSON clears, and automatic content invalidation.

Refresh the 404 design

After editing your 404 template, header, footer, navigation, or other content displayed on this page:

1. Open Settings → POM Cache → General → Cache tools in the relevant site.
2. Find Shared 404 page and select Delete 404 Cache.
3. Confirm the deletion message.
4. Visit a nonexistent URL as an anonymous visitor.
5. Confirm HTTP 404, the updated design, and X-POM-Cache-404: HIT when generation succeeds.

On multisite, use the current site's authorized settings context. Each site owns its own document. The dedicated action leaves ordinary HTML and progressive JSON untouched.

Public and reusable content only

Use a generic 404 design. Request-specific descriptions, visitor-specific content, and forms with expiring tokens should remain dynamic. The document is generated against a fixed missing URL, so templates that display the requested path will display that fixed path in the shared copy.

Logged-in visitors, session/cart bypass cookies, authorization headers, POST and other non-GET/HEAD methods, query parameters, REST/feed requests, and DONOTCACHEPAGE bypass this feature. Responses that set cookies, redirect, fail, or contain incomplete HTML cannot populate it. The only cookie exception is POM Translate's public base-language preference, which does not personalize the shared document. The HTML caching switch and existing shared-cache safety checks still apply.

One document is retained rather than separate copies for each language, device, or URL. It is served only on the configured site hostname and scheme, with the same language context as its generated copy. POM Translate's additional languages render dynamically. Integrations with other request-dependent output can disable sharing through the 404 filter.

If no document appears, check Shared 404 page for the last generation result. An attempted generation can report a failed connection, an unexpected HTTP status, non-HTML output, a cookie that prevents sharing, an unverified response, or a file-writing failure. Correct the reported condition, wait at least one minute, and visit a missing URL anonymously again. Delete 404 Cache also clears the previous attempt so the next eligible request can retry immediately.

The site must be able to make an anonymous HTTPS request to itself. Certificate errors, a firewall challenge, forced redirects, or personalized 404 responses can prevent generation. A CDN or proxy must preserve the generation request and the complete HTML response. Filtering a custom request header alone does not prevent generation when query parameters reach WordPress. WordPress continues serving its ordinary 404 whenever generation cannot complete safely.

This feature saves theme rendering. It does not eliminate WordPress startup, routing queries, or plugin work performed before template rendering, including an independently enabled 404 monitor.

Redirects

POM Cache tracks the common WordPress redirect statuses 301, 302, 303, and 307 and excludes those responses from HTML generation. A redirect should remain a status plus Location header, not become a reusable HTML page at the source URL.

For other custom non-200 flows, the integration should define DONOTCACHEPAGE explicitly and verify the result. Do not assume that a visually complete error template is sufficient protection.

wp_die() and interstitial errors

WordPress uses wp_die() for permission failures, confirmation screens, and other error/interstitial responses. POM Cache marks these requests with DONOTCACHEPAGE by default.

That protects content whose markup may include request-specific messages, nonces, or administrative context.

Fatal and incomplete output

Before writing, POM Cache checks for fatal PHP error types. It also requires non-empty output with a recognized closing marker.

Examples that should not become a page file:

• PHP stops before </html>;
• the output buffer is empty;
• a fatal error interrupts template rendering;
• a component deliberately defines DONOTCACHEPAGE.

The current visitor may still receive an error or partial response. The cache protection prevents that buffer from being promoted to index.html.

Previously cached pages during a failure

Generation and delivery are separate:

• if a valid static file is served before WordPress, the failing dynamic code may never run;
• if the request bypasses or misses, WordPress can fail, but the rejected buffer is not intentionally published;
• a CDN may continue serving its own older object regardless of the origin’s current state.

Decide operationally whether stale-but-valid content or an immediate dynamic failure is preferable. POM Cache HTML files do not expire by age, so purging during an outage removes that protection.

Test without affecting real error routes

Use a staging site:

1. delete the shared document with Delete 404 Cache;
2. request a known nonexistent URL and confirm status 404;
3. request a second missing URL and confirm it reuses the same document with HTTP 404, without creating either URL's index.html;
4. test a normal redirect and confirm its source path is not stored;
5. generate a valid page;
6. simulate an approved incomplete-output condition;
7. confirm the existing valid file was not replaced by a truncated one;
8. restore normal behavior and recheck the page.

Do not introduce fatal errors on production merely to test caching.

When an error file already exists

If visitors repeatedly receive an old error:

1. determine whether it comes from the CDN, Apache/POM Cache, another page-cache product, or the application;
2. inspect the stored file and its generation timestamp;
3. fix the underlying route or response first;
4. delete the affected origin cache;
5. invalidate the matching CDN object;
6. request the canonical URL and confirm the correct status, headers, and body.

Developer controls are documented in Error and 404 filters.