What causes "Unable to create the store directory (%s)." in symfony/http-kernel?

Create the directory manually and chmod/chown it so the PHP process user can write: mkdir -p /path && chown www-data:www-data /path.

symfony/http-kernel · critical · RuntimeException

Unable to create the store directory

Error message

Unable to create the store directory (%s).

What it means

Store::__construct() throws RuntimeException when the cache root directory does not exist and cannot be created via recursive mkdir (permissions, read-only filesystem, or path collision). The HTTP cache cannot operate without its storage directory.

Solutions

Create the directory manually and chmod/chown it so the PHP process user can write: mkdir -p /path && chown www-data:www-data /path.
Verify the configured root path is correct and on a writable filesystem.
Check disk space and mount flags (ro vs rw) in containers.

Example fix

// before
$store = new Store('/var/cache/http_cache'); // not writable
// after
if (!is_dir('/var/cache/http_cache')) { mkdir('/var/cache/http_cache', 0777, true); }
chmod('/var/cache/http_cache', 0777);
$store = new Store('/var/cache/http_cache');

Defensive patterns

Strategy: validation

Validate before calling

$root = '/var/cache/http_cache'; if ((!is_dir($root) && !@mkdir($root, 0777, true)) && !is_dir($root)) { // fail fast with clear deployment error }

Try / catch

try { $store = new Store($root); } catch (\RuntimeException $e) { // fall back to no-cache or abort deployment with clear message }

Prevention

Ensure cache dirs are created and writable at deploy time
Run PHP-FPM/CLI under a user owning var/cache
Avoid read-only root filesystems or mount a writable volume for cache

When it happens

Trigger: Constructing new Store('/path/to/cache') where the parent directory is not writable, the disk is full/read-only, or mkdir fails for any reason (@ suppresses the warning, then re-check fails).

Common situations: Deployments where var/cache lacks write permission for the PHP user, read-only container filesystems, or NFS mounts with permission issues.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

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

Appendix: source

Thrown at HttpCache/Store.php:47

    /** @var array<string, resource> */
    private array $locks = [];

    /**
     * Constructor.
     *
     * The available options are:
     *
     *   * private_headers  Set of response headers that should not be stored
     *                      when a response is cached. (default: Set-Cookie)
     *
     * @throws \RuntimeException
     */
    public function __construct(
        protected string $root,
        private array $options = [],
    ) {
        if (!is_dir($this->root) && !@mkdir($this->root, 0o777, true) && !is_dir($this->root)) {
            throw new \RuntimeException(\sprintf('Unable to create the store directory (%s).', $this->root));
        }
        $this->keyCache = new \SplObjectStorage();
        $this->options['private_headers'] ??= ['Set-Cookie'];
    }

    /**
     * Cleanups storage.
     */
    public function cleanup(): void
    {
        // unlock everything
        foreach ($this->locks as $lock) {
            flock($lock, \LOCK_UN);
            fclose($lock);
        }

        $this->locks = [];
    }

View on GitHub (pinned to aa3a39d728)