Skip to content

Troubleshooting

Requests are never served from a file

Check the response headers for X-Response-Filesystem-Cache: HIT. If it never appears, go through the conditions in Usage. The usual causes:

  • The visitor has a session cookie. Log out and clear cookies, or test with curl.
  • The request carries a query parameter not listed in query_allowlist.
  • The response declares a cache context other than url or languages, or a content-language context on a site with customised content language detection. Responses rendered through Drupal's HTML pipeline usually carry user.permissions, route or theme, so HTML pages are rarely eligible.
  • The mapping has reached its max_files limit. A warning is logged once until cron recounts; raise the limit or run cron more often.
  • The mapping is turned off on the settings form, or was ignored when read. Check the site log for errors from the response_filesystem_cache channel.

Internal Page Cache answers first

With the Internal Page Cache module enabled, a repeat anonymous request for a CacheableResponseInterface response is answered by the page cache before this module runs. Both store the response. This module then only serves responses the page cache does not store, such as plain Response and JsonResponse objects, and requests the page cache misses.

Files are rebuilt more often than expected

Core trims each database cache bin to 5,000 rows on cron, and every cache file uses two rows. When the limit removes a file's entry, cron deletes the file and the next request writes it again. Raise the limit for this bin in settings.php:

$settings['database_cache_max_rows']['bins']['response_filesystem_cache'] = 50000;

A file is still served after content changed

The file is invalidated only through the cache tags its response declared. A plain Response or JsonResponse declares none, so it lives until a router rebuild, a change to the anonymous role, or drush cr. Return a CacheableResponse with the right tags; see Extending.

Can the cache files be fetched by URL?

No. Drupal serves every hit itself. The cache directory carries a deny-all .htaccess, which Apache obeys, and file names include an HMAC keyed with the site's hash salt, so they cannot be computed on any server. An invalidated file therefore cannot be read while it waits for cron to delete it.

Changing $settings['hash_salt'] changes the names of new files. Existing files keep being served through their index entries until those are invalidated.

Can the web server serve the files without Drupal?

No, by design: a file served by the web server would keep being served after its content changed, until cron. Every request boots Drupal; the cache saves the work of the route, not the bootstrap.

Saving the settings form fails

In 1.0.0, saving the form threw ConfigValueException ("key contains a dot") whenever a mapping existed. Update and run drush updb; see Upgrading.