phalcon/cphalcon · error · Phalcon\Storage\Exceptions\InvalidConfiguration

The 'storageDir' must be specified in the options

Error message

The 'storageDir' must be specified in the options

What it means

Phalcon\Storage\Adapter\Stream (file-based cache, not the session adapter of the same name) requires options['storageDir'] at construction and, unlike Session\Adapter\Stream, has no php.ini fallback. A missing or empty value throws InvalidConfiguration('The \'storageDir\' must be specified in the options').

Source

Thrown at phalcon/Storage/Adapter/Stream.zep:62

    protected string storageDir = "";

    /**
     * Stream constructor.
     *
     * @phpstan-param storage_stream_options $options
     *
     * @throws InvalidConfiguration
     */
    public function __construct(
        <SerializerFactory> factory,
        array options = []
    ) {
        var storageDir;

        /** @var string $storageDir */
        let storageDir = this->getArrVal(options, "storageDir", "");
        if empty storageDir {
            throw new InvalidConfiguration(
                "The 'storageDir' must be specified in the options"
            );
        }

        /**
         * Lets set some defaults and options here
         */
        let this->storageDir = this->toDirSeparator(storageDir);

        parent::__construct(factory, options);

        this->initSerializer();
    }

    /**
     * Flushes/clears the cache
     */
    public function clear() -> bool

View on GitHub (pinned to b7419de9cd)

Solutions

1. Pass the option explicitly: new Stream($factory, ['storageDir' => '/var/cache/app'])
2. Fail fast on env resolution: $dir = getenv('CACHE_DIR'); if (!$dir) throw new RuntimeException('CACHE_DIR not set');
3. Use the exact camelCase key 'storageDir'; choose a directory on writable storage and create it before use

Example fix

// before
new Stream($factory); // InvalidConfiguration

// after
new Stream($factory, ['storageDir' => '/var/cache/app']);

$storageDir = (string) ($options['storageDir'] ?? getenv('CACHE_DIR'));
if ($storageDir === '') {
    throw new RuntimeException("storageDir missing: pass 'storageDir' or set CACHE_DIR");
}
if (!is_dir($storageDir)) {
    @mkdir($storageDir, 0775, true);
}

When it happens

Trigger: new Stream($serializerFactory) with an empty options array; key typo like 'storage_dir' or 'storagePath'; a storageDir value built from an env var that is unset and resolves to ''.

Common situations: Switching the cache adapter config to Stream and forgetting the directory; environment variable present in production but missing in CI or a colleague's machine; config files written for a different Phalcon version using snake_case.

Related errors

• The session save path cannot be empty
• Cannot set Memcached client options
• Cannot connect to the Memcached server(s)
• Redis server selected database failed
• Configuration file {fileName} cannot be loaded

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/a642140818b2918e. Report an issue: GitHub.