yiisoft/yii2 · error · InvalidConfigException

DbDependency::sql must be set.

Error message

DbDependency::sql must be set.

What it means

Thrown by yii\caching\DbDependency::generateDependencyData() when the dependency is evaluated with its sql property still null. DbDependency invalidates a cache entry by re-running a SQL query and comparing the result, so without a query there is nothing to compare and the configuration is invalid. The check runs lazily at cache-set/evaluation time, not at construction.

Source

Thrown at framework/caching/DbDependency.php:55

    /**
     * @var array the parameters (name => value) to be bound to the SQL statement specified by [[sql]].
     */
    public $params = [];


    /**
     * Generates the data needed to determine if dependency has been changed.
     * This method returns the value of the global state.
     * @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 [[db]] is not a valid application component ID
     */
    protected function generateDependencyData($cache)
    {
        /** @var Connection $db */
        $db = Instance::ensure($this->db, Connection::className());
        if ($this->sql === null) {
            throw new InvalidConfigException('DbDependency::sql must be set.');
        }

        if ($db->enableQueryCache) {
            // temporarily disable and re-enable query caching
            $db->enableQueryCache = false;
            $result = $db->createCommand($this->sql, $this->params)->queryOne();
            $db->enableQueryCache = true;
        } else {
            $result = $db->createCommand($this->sql, $this->params)->queryOne();
        }

        return $result;
    }
}

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Configure the query: new DbDependency(['sql' => 'SELECT MAX(updated_at) FROM post']).
2. If building from an array, verify the keys: ['class' => DbDependency::class, 'sql' => ..., 'params' => [...]].
3. Prefer DbQueryDependency with a Query object when you need composable/portable SQL instead of a raw string.
4. Add a construction-time assertion or factory method so a dependency is never created without its sql.

Example fix

// before
Yii::$app->cache->set('stats', $stats, 0, new DbDependency()); // sql === null -> throws on evaluation

// after
Yii::$app->cache->set('stats', $stats, 0, new DbDependency([
    'sql' => 'SELECT MAX(updated_at) FROM stats',
]));

// Build dependencies through one factory that refuses incomplete config
function dbDependency(string $sql, array $params = []): \yii\caching\DbDependency
{
    if (trim($sql) === '') {
        throw new \InvalidArgumentException('DbDependency requires a non-empty sql query.');
    }
    return new \yii\caching\DbDependency(['sql' => $sql, 'params' => $params]);
}

When it happens

Trigger: Calling Yii::$app->cache->set($key, $data, 0, new DbDependency()) without a sql config key; building the dependency from an array config where the key is misspelled or the whole 'dependency' array is empty; copying a FileDependency/ExpressionDependency config and forgetting to replace the property with sql; serializing/deserializing dependencies in a way that drops properties.

Common situations: Adding DB-based invalidation to an existing cache->set() call and omitting the sql; config assembled dynamically from a builder whose sql assignment is skipped for one code path; renaming the property during a refactor to a custom dependency subclass; fixture-based tests constructing dependencies directly.

Related errors

• "{class}::$query" should be an instance of "yii\db\QueryInte
• FileDependency::fileName must be set
• 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/1ab2573678bde9e4. Report an issue: GitHub.