DocumentationExperience Cloud KCS

AEM Dispatcher cache invalidation with statfileslevel and gracePeriod

Last update: October 22, 2026

When you configure Adobe Experience Manager (AEM) Dispatcher with statfileslevel and gracePeriod, explicit cache clearing for listing pages is generally unnecessary if the listing and the updated content are under the same .stat file scope. Verify your statfileslevel setting to confirm both are covered.

Description description

Symptoms

Customer asks whether explicit cache clearing (invalidation type INVALIDATE) is needed for listing pages after content is updated with type ADD. With /publishfarm/cache/statfileslevel "2" and /publishfarm/cache/gracePeriod "2", listing pages appear to refresh without it.

Steps to reproduce

  1. Configure /publishfarm/cache/statfileslevel "2" and /publishfarm/cache/gracePeriod "2".
  2. Invalidate a file under .stat with type ADD. The .stat file’s modification date updates.
  3. Request a file matching /invalidate/../type "allow" within 2 seconds. Result: actionhit, cache unchanged.
  4. Request it again after 2 seconds. Result: actionmiss, cache refreshed.

Cause

ADD updates the .stat file’s timestamp. Files matching allow rules are treated as invalid only after gracePeriod has elapsed since that timestamp. When the updated content and the listing page share the same .stat scope, the listing is invalidated by the same mechanism, so a separate INVALIDATE is unnecessary.

Resolution resolution

Follow the steps below to resolve the issue:

  1. Understand statfileslevel and gracePeriod behavior: When invalidate.cache is triggered (for example, by publishing a page), Dispatcher creates or updates the .stat file at the configured statfileslevel.
  2. On the next request for a cached page, Dispatcher compares the timestamps of the .stat file and the cached file. If the .stat file is newer, the cache is invalidated and content is fetched from Publish.
  3. The gracePeriod setting (for example, 2 seconds) delays cache invalidation for the specified duration after the .stat file is updated. Requests within the gracePeriod return the cached content (actionhit). After the gracePeriod, the cache is invalidated (actionmiss).
  4. If your configuration triggers invalidate.cache on publishing a page, and both the updated content and its listing are under the same .stat file scope, explicit cache clearing for the listing page is generally unnecessary. The listing will be invalidated automatically after the gracePeriod.
  5. Ensure that the statfileslevel setting covers both the updated content and the listing page under the same .stat file.
  6. Monitor logs for edge cases where invalidate.cache is triggered continuously, as cache invalidation timing may shift. Adjust gracePeriod as needed.

Verify that cache invalidation occurs as expected after the gracePeriod and that explicit INVALIDATE operations are not required for listing pages under the same .stat file scope.

recommendation-more-help
experience-cloud-kcs-help-kbarticles