{"record":{"id":"a642140818b2918e","repo":"phalcon/cphalcon","slug":"the-storagedir-must-be-specified-in-the-options","errorCode":null,"errorMessage":"The 'storageDir' must be specified in the options","messagePattern":"The 'storageDir' must be specified in the options","errorType":"exception","errorClass":"Phalcon\\Storage\\Exceptions\\InvalidConfiguration","httpStatus":null,"severity":"error","filePath":"phalcon/Storage/Adapter/Stream.zep","lineNumber":62,"sourceCode":"    protected string storageDir = \"\";\n\n    /**\n     * Stream constructor.\n     *\n     * @phpstan-param storage_stream_options $options\n     *\n     * @throws InvalidConfiguration\n     */\n    public function __construct(\n        <SerializerFactory> factory,\n        array options = []\n    ) {\n        var storageDir;\n\n        /** @var string $storageDir */\n        let storageDir = this->getArrVal(options, \"storageDir\", \"\");\n        if empty storageDir {\n            throw new InvalidConfiguration(\n                \"The 'storageDir' must be specified in the options\"\n            );\n        }\n\n        /**\n         * Lets set some defaults and options here\n         */\n        let this->storageDir = this->toDirSeparator(storageDir);\n\n        parent::__construct(factory, options);\n\n        this->initSerializer();\n    }\n\n    /**\n     * Flushes/clears the cache\n     */\n    public function clear() -> bool","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Storage/Adapter/Stream.zep#L44-L80","documentation":"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').","triggerScenarios":"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 ''.","commonSituations":"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.","solutions":["Pass the option explicitly: new Stream($factory, ['storageDir' => '/var/cache/app'])","Fail fast on env resolution: $dir = getenv('CACHE_DIR'); if (!$dir) throw new RuntimeException('CACHE_DIR not set');","Use the exact camelCase key 'storageDir'; choose a directory on writable storage and create it before use"],"exampleFix":"// before\nnew Stream($factory); // InvalidConfiguration\n\n// after\nnew Stream($factory, ['storageDir' => '/var/cache/app']);","handlingStrategy":"validation","validationCode":"$storageDir = (string) ($options['storageDir'] ?? getenv('CACHE_DIR'));\nif ($storageDir === '') {\n    throw new RuntimeException(\"storageDir missing: pass 'storageDir' or set CACHE_DIR\");\n}\nif (!is_dir($storageDir)) {\n    @mkdir($storageDir, 0775, true);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the exact camelCase key 'storageDir' — snake_case silently misses","Assert required env vars at boot so empty strings fail with your message, not Phalcon's","Create the directory (or provision it) during deploy, not lazily at runtime"],"tags":["php","phalcon","cache","configuration","filesystem"],"backgroundTag":"missing-config-path","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}