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
urlorlanguages, or a content-language context on a site with customised content language detection. Responses rendered through Drupal's HTML pipeline usually carryuser.permissions,routeortheme, so HTML pages are rarely eligible. - The mapping has reached its
max_fileslimit. 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_cachechannel.
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.