yiisoft/yii2 · error · InvalidConfigException

FileDependency::fileName must be set

Error message

FileDependency::fileName must be set

What it means

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.

Source

Thrown at framework/caching/FileDependency.php:44

{
    /**
     * @var string the file path or [path alias](guide:concept-aliases) whose last modification time is used to
     * check if the dependency has been changed.
     */
    public $fileName;


    /**
     * Generates the data needed to determine if dependency has been changed.
     * This method returns the file's last modification time.
     * @param CacheInterface $cache the cache component that is currently evaluating this dependency
     * @return mixed the data needed to determine if dependency has been changed.
     * @throws InvalidConfigException if [[fileName]] is not set
     */
    protected function generateDependencyData($cache)
    {
        if ($this->fileName === null) {
            throw new InvalidConfigException('FileDependency::fileName must be set');
        }

        $fileName = Yii::getAlias($this->fileName);

        clearstatcache(false, $fileName);
        return @filemtime($fileName);
    }
}

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Set fileName when creating the dependency: new FileDependency(['fileName' => '@app/config/params.php']).
2. Check exact key casing in array configs: it is fileName (camelCase).
3. 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).

Example fix

// before
Yii::$app->cache->set('params', $params, 0, new FileDependency()); // fileName === null -> throws

// after
Yii::$app->cache->set('params', $params, 0, new FileDependency([
    'fileName' => '@app/config/params.php', // alias is resolved via Yii::getAlias()
]));

$fileName = Yii::getAlias($configuredFile);
if ($fileName === null || $fileName === '') {
    // no file to watch: cache without this dependency or pick TagDependency
    Yii::$app->cache->set($key, $data);
    return;
}
Yii::$app->cache->set($key, $data, 0, new \yii\caching\FileDependency(['fileName' => $fileName]));

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• DbDependency::sql must be set.
• "{class}::$query" should be an instance of "yii\db\QueryInte
• The 'host' property must be specified for every memcache ser
• You should configure "cache" component to use database befor
• Cost must be between 4 and 31.

AI-assisted analysis of yiisoft/yii2@66f00d18a2 (2026-08-17). Data as JSON: /api/errors/c06c7adbdfb7fca7. Report an issue: GitHub.