What causes "Failed to write cache file "%s"." in symfony/http-kernel?

Fix filesystem permissions: chown/chgrp the cache directory to the PHP user and ensure it is writable (chmod -R 775 var/cache).

symfony/http-kernel · critical · RuntimeException

Failed to write cache file

Error message

Failed to write cache file "%s".

What it means

CacheWarmer::writeCacheFile() writes cache content atomically (temp file + rename) and throws RuntimeException when either file_put_contents or rename fails. This guarantees the cache file either exists fully or an error is raised, rather than silently producing broken cache files.

Solutions

Fix filesystem permissions: chown/chgrp the cache directory to the PHP user and ensure it is writable (chmod -R 775 var/cache).
Ensure the cache directory exists before warming (mkdir -p) and that the disk is not full.
Run cache:warmup as the same user the web server/PHP-FPM uses, not root.

Example fix

// before (deployment)
sudo php bin/console cache:warmup   # runs as root, files owned by root
// after
sudo -u www-data php bin/console cache:warmup
sudo chown -R www-data:www-data var/cache

Defensive patterns

Strategy: try-catch

Validate before calling

if (!is_dir($cacheDir) || !is_writable($cacheDir)) {
    throw new \RuntimeException(sprintf('Cache dir %s missing or not writable', $cacheDir));
}

Try / catch

try { $warmer->warmUp($cacheDir, $buildDir); } catch (\RuntimeException $e) { if (str_contains($e->getMessage(), 'Failed to write cache file')) { /* check permissions/disk, retry as correct user */ } throw $e; }

Prevention

Run cache warming as the web/PHP user, never root
Ensure var/cache exists and is writable before deploy
Monitor disk space on cache volumes

When it happens

Trigger: warmUp() (or any caller passing through writeCacheFile) targets a cache directory that does not exist, is read-only, or is owned by another user (e.g. var/cache owned by root after running console as root); rename fails across filesystems or due to permissions.

Common situations: Deploy as root then run app as www-data; full disk; var/cache deleted without recreating permissions; SELinux/AppArmor blocking writes; shared hosting with restricted umask.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of symfony/http-kernel@aa3a39d728 (2026-09-13). Data as JSON: /api/errors/0ec0332005978c24. Report an issue: GitHub.

Appendix: source

Thrown at CacheWarmer/CacheWarmer.php:30

namespace Symfony\Component\HttpKernel\CacheWarmer;

/**
 * Abstract cache warmer that knows how to write a file to the cache.
 *
 * @author Fabien Potencier <fabien@symfony.com>
 */
abstract class CacheWarmer implements CacheWarmerInterface
{
    protected function writeCacheFile(string $file, $content): void
    {
        $tmpFile = @tempnam(\dirname($file), basename($file));
        if (false !== @file_put_contents($tmpFile, $content) && @rename($tmpFile, $file)) {
            @chmod($file, 0o666 & ~umask());

            return;
        }

        throw new \RuntimeException(\sprintf('Failed to write cache file "%s".', $file));
    }
}

View on GitHub (pinned to aa3a39d728)