Trace one HTML cache generation request

Use the wp pom-cache generate_debug command when one public page does not create its expected index.html file and the normal configuration checks do not explain why. The command makes one real anonymous frontend request and reports each POM Cache decision without requiring WP_DEBUG or persistent debug logging.

The request follows the normal WordPress rendering path and can create or replace the target page's static HTML file. Run it only for a public page whose shared output is safe to cache.

Prerequisites

• Shell access with WP-CLI available.
• POM Cache active on the selected site.
• The correct multisite site selected with the global --url option.
• An absolute public --page-url whose host matches that selected site's home URL.
• An origin that can receive an HTTP request from the server running WP-CLI.

The command does not require WordPress debug mode, Query Monitor, or an authenticated browser session.

Run a normal diagnostic

Use the global --url option to select the WordPress site and --page-url to identify the frontend page:

wp --url=https://www.example.com pom-cache generate_debug \
  --page-url=https://www.example.com/

The command arms a five-minute request token, makes a cookie-free request, removes its private diagnostic parameter before normal eligibility checks, and deletes the stored trace when the command finishes.

To compare a working page with a failing page, run the command once for each exact URL:

wp --url=https://www.example.com pom-cache generate_debug \
  --page-url=https://www.example.com/working-page/

wp --url=https://www.example.com pom-cache generate_debug \
  --page-url=https://www.example.com/

Bypass a CDN or reverse proxy

If the public hostname resolves to a CDN, pass a full origin or loopback URL with the same path and query:

wp --url=https://www.example.com pom-cache generate_debug \
  --page-url=https://www.example.com/ \
  --request-url=http://127.0.0.1/

The command sends the public host in the HTTP Host header so WordPress selects the intended multisite site. Only the scheme, host, and port may differ between --request-url and --page-url.

Use --skip-ssl-verify only for a trusted local or private HTTPS origin with a certificate that WP-CLI cannot validate. Do not use it for a normal public request. Use --timeout=<seconds> to change the HTTP timeout from its 20-second default; accepted values are 5 through 60.

Read the result

The trace table follows the request through these stages:

1. bootstrap proves that the token reached WordPress, matched the intended URL, and was removed before cache evaluation.
2. phase2 proves that POM Cache started its HTML output buffer or explains why it did not.
3. pom_cache_ob_callback reports the exact request-level eligibility result.
4. pom_cache_get_ob reports the response-completeness check and every relevant directory, temporary-file, write, size, and rename result.

A successful conclusion includes the exact final index.html path and byte count. An abandoned or failed conclusion includes a stable reason code. Common reason codes include:

• donotcachepage_defined: another component defined DONOTCACHEPAGE during rendering;
• query_string: the real target URL contains a query string;
• is_redirect, is_rest, is_feed, or is_robots: WordPress classified the response as an excluded request type;
• unknown_page_type: WordPress did not identify a known page type;
• missing_eof_marker: the final output lacks a recognized closing HTML, feed, sitemap, or XML marker;
• cache_directory_unavailable or temporary_file_open_failed: the directory or temporary file could not be created;
• cache_file_publish_failed: the temporary file could not be renamed to the final cache file;
• static_file_written: the complete static HTML file was written successfully.

The table may include absolute cache paths, permissions, PHP filesystem errors, response status, response headers, and cookie names when a cookie caused the bypass. It never stores the response body, cookie values, authorization headers, or the clear diagnostic token.

Treat the output as private operational evidence: remove unnecessary absolute paths and infrastructure headers before sharing it outside your support channel.

If no trace reaches WordPress

No trace reached WordPress means the HTTP request did not reach this POM Cache installation with its diagnostic token. Typical causes are a CDN cache hit, a proxy that removes the query or custom header, DNS routing to another origin, or an HTTP connection failure.

Retry with --request-url pointed directly at the origin. Also verify that the public host still matches the site selected by --url and that the origin routes the supplied Host header to the correct multisite site.

What this command does not prove

The command proves whether POM Cache generated the origin static HTML file and shows selected response headers. It does not prove that Apache, Nginx, CloudFront, or another CDN later serves that file, caches it, or compresses it. After a successful write, continue with Verify a cache hit and Verify response compression.