Diagnosing Zend Cache Filesystem Write Failures

What’s the problem?

In a Zend Framework or Laminas application you notice two things:

• Application logs contain lines like Unable to write to /var/cache/zend.
• Cached items that should persist between requests are missing on the next request.

The underlying issue is almost always that the Zend\Cache\Storage\Adapter\Filesystem adapter cannot create or modify files in the configured directory. The goal of this guide is to give you a concise, ordered checklist that pinpoints the exact cause and shows how to fix it.

Diagnose in order: path, permissions, ownership, security, PHP settings

Below is a step‑by‑step flow. Follow the steps in the order shown; each step either confirms the hypothesis or eliminates it. Use the example commands as a reference; replace /var/cache/zend with your actual cache path.

1. Verify the configured path
   • Open your module or application configuration file (e.g. module.config.php or config/autoload/cache.local.php).
   • Locate the cache_dir setting for the Filesystem adapter.
   • Confirm the path is absolute and points to the intended directory.

   Example snippet:

   $config = [
       'cache' => [
           'adapter' => [
               'name' => 'Filesystem',
               'options' => [
                   'cache_dir' => '/var/cache/zend',
               ],
           ],
       ],
   ];
   

2. Confirm the directory exists
   • Run from the command line as the user that runs the web server (often www-data or apache):

     ls -ld /var/cache/zend

   • If the command returns “No such file or directory”, create it:

     mkdir -p /var/cache/zend

3. Check read/write permissions
   • View the current mode:

     ls -ld /var/cache/zend

   • Typical safe mode for a web‑served cache is 0755 with the web server user as owner. If the directory is locked to root or another account, the adapter cannot write.
   • Adjust permissions if necessary:

     # Set group to web server user and give group write
     chgrp www-data /var/cache/zend
     chmod 0775 /var/cache/zend
     # Or, if you are certain no other user needs access, 0777 (use sparingly)
     chmod 0777 /var/cache/zend
     

   • Verify PHP can write:

     php -r "var_dump(is_writable('/var/cache/zend'));"
     

4. Verify ownership
   • Ownership should be the web server user (or a dedicated cache user). If the process runs as www-data but the directory is owned by root, writes fail.

     chown -R www-data:www-data /var/cache/zend

5. Inspect SELinux/AppArmor policies
   • On SELinux‑enabled systems, the default context may block writes to arbitrary paths.

     ls -Z /var/cache/zend

   • Check audit logs for denials:

     grep cache /var/log/audit/audit.log | tail
     

   • If you see AVC denials, either move the cache directory into a context that allows writes (e.g. /var/cache/zend → /var/cache/httpd/cache) or create a custom policy rule. For a quick test, temporarily set SELinux to permissive:

     setenforce 0

   • For AppArmor, use aa-status and aa-logprof to see if the profile blocks write on the path.
6. Ensure PHP error logging is enabled
   • The adapter logs a warning to the PHP error log when it cannot write. If error logging is suppressed, you’ll miss the warning.
   • Check php.ini or .htaccess for:

     error_log = /var/log/php-fpm/www-error.log
     error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
     display_errors = Off
     

   • After making changes, restart the PHP-FPM or web server service.
7. Test a cache write
   • Clear any existing cache files to avoid confusion:

     rm -rf /var/cache/zend/*
     

   • Trigger a cache write in the application (e.g. load a page that uses caching). Then re‑run the PHP check:

     php -r "var_dump(is_writable('/var/cache/zend'));"
     

   • Inspect the log file you pointed error_log to; you should see a line like Cache adapter Filesystem: Unable to write to /var/cache/zend only if the problem persists.
8. Check disk and inode limits
   • If the directory exists and permissions look correct but writes still fail, the disk may be full or the inode quota exhausted.

     df -h /var/cache/zend
     df -i /var/cache/zend
     

   • Free space or inode usage above 90% indicates a likely cause.
9. Verify the adapter is instantiated correctly
   • In the bootstrap or service manager configuration, confirm that the Filesystem adapter is being used and that the cache_dir option is passed.
   • Example of a mis‑configured adapter that defaults to /tmp:

     $cache = new Zend\Cache\Storage\Adapter\Filesystem(); // missing options
     

   • Correct it by passing the options array.
10. Escalation criteria
    1. If after all the above the cache still fails, gather the following evidence before escalating:
       • Exact log lines from the PHP error log.
       • Output of phpinfo() showing error_reporting and display_errors settings.
       • Results of ls -ldZ showing SELinux context.
       • Disk usage stats.
    2. Submit a ticket to the Zend/Laminas community or open a GitHub issue with the gathered data. Be sure to note the PHP version and OS distribution, as certain releases have known bugs with the Filesystem adapter.

Quick reference table

Problem	Likely Cause	Quick Fix
Log says “Unable to write to …”	Directory missing or wrong path	Create directory; verify path in config
Log is silent; cache missing	Permissions/ownership wrong	chmod 0775; chown www-data
Log shows SELinux denial	SELinux/AppArmor blocking write	Adjust policy or set permissive for test
Disk full or inode exhaustion	No space left on device	Free space or expand filesystem
Adapter not instantiated correctly	Missing options array	Pass cache_dir option explicitly

Limitations and cautions

• Setting the directory to 0777 is a quick fix but exposes the cache to all users; restrict to 0755 where possible.
• Disabling SELinux or AppArmor removes a security layer; prefer a targeted policy rule.
• Changing ownership to the web server user may affect other services that write to the same location.
• Enabling PHP error logging can reveal sensitive stack traces; keep display_errors off in production.
• If the cache directory resides on NFS, permission semantics differ; verify no_root_squash and all_squash mount options.

Conclusion

Most “write‑to‑disk” failures in Zend’s Filesystem cache are down to a simple mis‑configuration: wrong path, missing directory, or inadequate permissions. By following the ordered checks above you can isolate the root cause quickly and apply the precise fix. Remember to verify each step with PHP’s is_writable() test and by inspecting the error log. If the problem persists after all checks, gather the evidence outlined in the escalation section and involve your system or security team.