Troubleshoot progressive JSON caching

Start with the visible symptom, then identify whether the failure is generation, storage, delivery, invalidation, or CDN freshness. Changing several switches at once makes the active layer harder to prove.

Establish a controlled test

Before using the symptom sections:

1. Test a real POM Theme progressive archive;
2. Copy one clean .json URL from the browser network panel;
3. Use a logged-out private window with an empty cart;
4. Bypass the CDN through an approved origin-testing method;
5. Remove all query parameters;
6. Temporarily leave Apache JSON delivery out of the test;
7. Enable the JSON master, PHP early serving, WordPress fallback, and writes;
8. Clear the progressive JSON cache.

Request once for generation and a second time for reuse.

No JSON files are created

Check the first response header.

If it says:

X-POM-Progressive-Archive-Cache: generated-dynamic

the theme did not classify the response as reusable. Confirm you are testing the clean progressive route, not a filtered or otherwise dynamic variant.

If it says:

X-POM-Progressive-Archive-Cache: generated-cacheable

but the count stays at zero, check:

• Progressive JSON cache is enabled;
• JSON writes is enabled;
• the JSON byte size is within Maximum JSON file size;
• Cache Location exists or can be created;
• PHP can write the destination directory;
• the response is valid, non-empty JSON;
• the test is on the same multisite site whose summary you are viewing.

Do not assume a successful response proves a successful write; WordPress can still return the dynamically generated JSON.

A file exists, but every request is dynamic

Determine whether the stored path matches the requested context:

• host and subsite path;
• locale prefix;
• post type;
• context hash;
• archive mode;
• page number;
• items per page.

Then confirm:

• WordPress read fallback is enabled for a router-level test;
• the request has an empty query string;
• the file is readable, non-empty, valid JSON, and within the current maximum;
• current archive settings still match the URL;
• no supported extension rejects the cached response.

Disable Apache and PHP early delivery temporarily. If the theme reports hit, the file is valid and the earlier problem lies in request eligibility or drop-in/server mapping.

WordPress fallback hits, but PHP early serving does not

This narrows the problem considerably. Review:

• PHP early static serving;
• POM Cache → Advanced → WordPress configuration;
• whether the correct advanced-cache.php drop-in loads;
• WP_CACHE status;
• login, password, comment, WooCommerce session, and cart cookies;
• DONOTCACHEPAGE;
• query parameters;
• public route shape and home subdirectory.

The fallback proves POM Cache can find and validate the JSON after WordPress loads. Focus on the early bootstrap and request state.

Apache returns a 404 or HTML

Restore the prior rule configuration, then compare:

• rule placement before the WordPress block;
• actual Apache document root;
• current Cache Location;
• pom-cache-json subdirectory;
• %{SERVER_NAME} versus the site's home host;
• subdirectory multisite path;
• locale prefix mapping;
• mod_rewrite and mod_headers availability.

A content type of text/html often means the request fell through to a WordPress error page. A 404 can mean the physical target did not match the file POM Cache wrote.

Keep PHP early serving active as the fallback while correcting the server rule.

The second request has no diagnostic cache header

Possible explanations:

• Apache served the file and PHP never ran;
• the CDN served a stored response;
• the request bypassed static delivery;
• another layer removed or replaced headers.

Test directly against the origin with Apache temporarily disabled. Do not use response speed alone to declare a cache hit.

A batch is stale after editing a post

Verify:

• Purge JSON on post changes is enabled;
• the JSON master was enabled when hooks were registered for the request;
• the edited content type is public/viewable;
• the change was a normal post lifecycle event rather than a direct data write;
• the stale output is in a later JSON batch, not the initial HTML shell;
• the origin file was actually deleted;
• the CDN is not returning an older copy.

Changing the terms assigned to a post also depends on the post-change switch.

A taxonomy label or order is stale

Use Purge JSON on term changes for term creation, editing, deletion, and compatible term-order changes.

Use Purge JSON on post changes when the action was assigning a term to a post. These are separate paths.

For custom term metadata that changes visible output, clear manually unless the owning integration provides an invalidation.

One language remains stale

Confirm:

• Purge JSON on translation changes is enabled;
• the translation was saved through a supported POM Translate workflow;
• the public route has the expected locale prefix;
• both old and new slug paths have been considered;
• HTML was cleared too if the old text is in the initial page;
• the CDN does not retain the localized JSON URL.

Automatic translation invalidation clears all current-site JSON locales, so a remaining origin file usually indicates that no supported notification ran or you are inspecting another site's namespace.

Responses above the maximum never hit

Measure the response body in bytes. The default is 1,048,576 bytes and the limit applies on both write and read.

Before increasing it:

• reduce excessive items per batch;
• inspect unusually large rendered card markup;
• make sure a debug payload is not being included;
• compare standard and split archive modes.

If a larger response is legitimate, increase the limit deliberately and retest memory, storage, and transfer cost.

The tools count is unexpectedly high

POM Cache does not age files out. Old context hashes, retired routes, deep batches, languages, and term sections remain until invalidation.

Perform a manual JSON clear and let real traffic rebuild the working set. If growth resumes unexpectedly, relate new files to current route dimensions rather than deleting on a timer without understanding demand.

Clearing origin does not update visitors

The likely remaining layer is the CDN or browser HTTP cache:

1. Verify the source change;
2. Clear JSON at the origin;
3. Request and verify regenerated origin content;
4. Invalidate the smallest affected CDN viewer paths;
5. Wait for completion;
6. Request publicly and inspect edge cache status.

The configured Cache-Control controls downstream freshness, not origin-file deletion.

Escalation information

When requesting support, provide non-sensitive evidence:

• WordPress and POM Cache versions;
• single-site or multisite and whether the affected site is path- or domain-mapped;
• hosting layer: Apache, Nginx, proxy, and CDN;
• the route shape with private identifiers removed if necessary;
• the four JSON runtime switch states;
• maximum file size and cache-control policy;
• first and second response headers;
• whether Progressive JSON Cache Contents changed;
• whether the issue reproduces at origin;
• exact editorial action expected to invalidate the cache.

Never include license keys, authentication cookies, private server paths, or credentials.