yiisoft/yii2 · error · yii\base\InvalidConfigException

You should configure "cache" component to use database befor

Error message

You should configure "cache" component to use database before executing this migration.

What it means

Thrown by the framework cache migration m150909_153426_cache_init when Yii::$app->getCache() does not return a yii\caching\DbCache instance. The migration creates the table DbCache stores its data in, so it insists that the application's cache component (in the configuration the migration runs under, normally console config) already points at a database-backed cache. Any other cache class (FileCache, RedisCache, dummy default) is treated as running the migration against the wrong setup.

Source

Thrown at framework/caching/migrations/m150909_153426_cache_init.php:29

use yii\db\Migration;

/**
 * Initializes Cache tables.
 *
 * @author Misbahul D Munir <misbahuldmunir@gmail.com>
 * @since 2.0.7
 */
class m150909_153426_cache_init extends Migration
{
    /**
     * @throws yii\base\InvalidConfigException
     * @return DbCache
     */
    protected function getCache()
    {
        $cache = Yii::$app->getCache();
        if (!$cache instanceof DbCache) {
            throw new InvalidConfigException('You should configure "cache" component to use database before executing this migration.');
        }

        return $cache;
    }

    /**
     * {@inheritdoc}
     */
    public function up()
    {
        $cache = $this->getCache();
        $this->db = $cache->db;

        $tableOptions = null;
        if ($this->db->driverName === 'mysql') {
            // https://stackoverflow.com/questions/766809/whats-the-difference-between-utf8-general-ci-and-utf8-unicode-ci
            $tableOptions = 'CHARACTER SET utf8 COLLATE utf8_unicode_ci ENGINE=InnoDB';
        }

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Configure the console application's cache as DbCache before running the migration: in config/console.php set 'cache' => ['class' => \yii\caching\DbCache::class, 'db' => 'db' (or a dedicated cache connection).
2. Verify with php yii (help/inspect) or a tinker script that Yii::$app->cache is DbCache in the CLI context, then re-run the migration.
3. If you do not intend to use DbCache, remove the @yii/caching/migrations path from the migrate command — this migration is only needed for database-backed cache.

Example fix

// before: config/console.php has no/other cache component
// $ php yii migrate --migrationPath=@yii/caching/migrations
// -> 'You should configure "cache" component to use database before executing this migration.'

// after: config/console.php
'components' => [
    'cache' => [
        'class' => \yii\caching\DbCache::class,
        'db' => 'db',
    ],
],
// $ php yii migrate --migrationPath=@yii/caching/migrations  // now creates the cache table

// Pre-flight before running the cache migrations (console context)
if (!(Yii::$app->get('cache', false) instanceof \yii\caching\DbCache)) {
    throw new \yii\console\Exception(
        'Configure components.cache as yii\caching\DbCache (console config) before running caching migrations.'
    );
}

function isDbCache($component): bool
{
    return $component instanceof \yii\caching\DbCache;
}

When it happens

Trigger: Running php yii migrate --migrationPath=@yii/caching/migrations while the console application's 'cache' component is FileCache or MisCache/MemCache; cache not configured at all in console config (web-only component); a project where web config uses DbCache but config/console.php still has the default; CI running migrations with a minimal config that omits the cache component.

Common situations: First-time setup of DbCache following the guide: developer added DbCache to web config but migrations run under console config; environments with split web/console configs drifting apart; automated deploy pipelines that use a stripped-down console config for migrate; adding the migration path to the application's migrationNamespaces without completing the cache switch everywhere.

Related errors

• DbDependency::sql must be set.
• "{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
• Cost must be between 4 and 31.

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