{"record":{"id":"c06c7adbdfb7fca7","repo":"yiisoft/yii2","slug":"filedependency-filename-must-be-set","errorCode":null,"errorMessage":"FileDependency::fileName must be set","messagePattern":"FileDependency::fileName must be set","errorType":"exception","errorClass":"InvalidConfigException","httpStatus":null,"severity":"error","filePath":"framework/caching/FileDependency.php","lineNumber":44,"sourceCode":"{\n    /**\n     * @var string the file path or [path alias](guide:concept-aliases) whose last modification time is used to\n     * check if the dependency has been changed.\n     */\n    public $fileName;\n\n\n    /**\n     * Generates the data needed to determine if dependency has been changed.\n     * This method returns the file's last modification time.\n     * @param CacheInterface $cache the cache component that is currently evaluating this dependency\n     * @return mixed the data needed to determine if dependency has been changed.\n     * @throws InvalidConfigException if [[fileName]] is not set\n     */\n    protected function generateDependencyData($cache)\n    {\n        if ($this->fileName === null) {\n            throw new InvalidConfigException('FileDependency::fileName must be set');\n        }\n\n        $fileName = Yii::getAlias($this->fileName);\n\n        clearstatcache(false, $fileName);\n        return @filemtime($fileName);\n    }\n}\n","sourceCodeStart":26,"sourceCodeEnd":53,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/caching/FileDependency.php#L26-L53","documentation":"Thrown by yii\\caching\\FileDependency::generateDependencyData() when the dependency is evaluated with fileName still null. FileDependency invalidates cache entries by remembering a file's modification time (filemtime), so a dependency without a file to watch is incomplete and rejected. Like the other cache dependencies, the check fires lazily when the cache value is set/evaluated, not when the object is created.","triggerScenarios":"Yii::$app->cache->set($key, $data, 0, new FileDependency()) with no fileName; array config with a misspelled key ('filename' vs 'fileName') so the property stays null; a dependency built from merged configs where the fileName entry was dropped; passing an alias string is fine, but passing null explicitly (e.g. from a variable that is null) also triggers it.","commonSituations":"Caching parsed config or CSV/XML imports keyed on the source file's mtime and forgetting the property on one call site; config assembled via ArrayHelper::merge where a later empty dependency array overwrote fileName; tutorial code adapted from DbDependency leaving the old property name.","solutions":["Set fileName when creating the dependency: new FileDependency(['fileName' => '@app/config/params.php']).","Check exact key casing in array configs: it is fileName (camelCase).","If the file is dynamic, compute the path first and only build the dependency when it is non-null; otherwise pick a different dependency type (TagDependency, DbDependency)."],"exampleFix":"// before\nYii::$app->cache->set('params', $params, 0, new FileDependency()); // fileName === null -> throws\n\n// after\nYii::$app->cache->set('params', $params, 0, new FileDependency([\n    'fileName' => '@app/config/params.php', // alias is resolved via Yii::getAlias()\n]));","handlingStrategy":"validation","validationCode":"$fileName = Yii::getAlias($configuredFile);\nif ($fileName === null || $fileName === '') {\n    // no file to watch: cache without this dependency or pick TagDependency\n    Yii::$app->cache->set($key, $data);\n    return;\n}\nYii::$app->cache->set($key, $data, 0, new \\yii\\caching\\FileDependency(['fileName' => $fileName]));","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set fileName in the same expression that constructs the FileDependency","Watch the camelCase key name (fileName) in array configs — 'filename' silently does nothing","When the watched file is dynamic/optional, check the path is non-null first or choose a different dependency type"],"tags":["php","yii2","cache","dependency","filesystem","configuration"],"backgroundTag":"missing-required-config","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}