yiisoft/yii2 · critical · yii\base\InvalidConfigException

The table does not exist: {table}

Error message

The table does not exist: {table}

What it means

ActiveRecord::getTableSchema() asks the DB connection's schema reader for the schema of tableName(); when the reader returns null the connection cannot see any such table, and InvalidConfigException is thrown. The call happens implicitly on first AR use (attribute detection, find, insert), so any model mapped to a missing table fails on its first query.

Source

Thrown at framework/db/ActiveRecord.php:438

     */
    public static function tableName()
    {
        return '{{%' . Inflector::camel2id(StringHelper::basename(get_called_class()), '_') . '}}';
    }

    /**
     * Returns the schema information of the DB table associated with this AR class.
     * @return TableSchema the schema information of the DB table associated with this AR class.
     * @throws InvalidConfigException if the table for the AR class does not exist.
     */
    public static function getTableSchema()
    {
        $tableSchema = static::getDb()
            ->getSchema()
            ->getTableSchema(static::tableName());

        if ($tableSchema === null) {
            throw new InvalidConfigException('The table does not exist: ' . static::tableName());
        }

        return $tableSchema;
    }

    /**
     * Returns the primary key name(s) for this AR class.
     * The default implementation will return the primary key(s) as declared
     * in the DB table that is associated with this AR class.
     *
     * If the DB table does not declare any primary key, you should override
     * this method to return the attributes that you want to use as primary keys
     * for this AR class.
     *
     * Note that an array should be returned even for a table with single primary key.
     *
     * @return string[] the primary keys of the associated database table.
     */

View on GitHub (pinned to 66f00d18a2)

Solutions

  1. Run the pending migrations, or verify the table exists with the same connection the model uses
  2. Check tableName() spelling and the Connection::tablePrefix value for {{%...}} names
  3. Confirm the model's getDb() returns the connection that actually holds the table
  4. Flush the schema cache after DDL changes (e.g. Yii::$app->cache->flush() or disable enableSchemaCache while developing)

Example fix

// before
class Payment extends ActiveRecord
{
    public static function tableName() { return 'payements'; } // typo
}

// after
class Payment extends ActiveRecord
{
    public static function tableName() { return '{{%payments}}'; }
}
Defensive patterns

Strategy: validation

Validate before calling

if (Model::getDb()->getSchema()->getTableSchema(Model::tableName()) === null) {
    throw new InvalidConfigException('Table ' . Model::tableName() . ' missing on this connection. Run migrations.');
}

Try / catch

try {
    $rows = Model::find()->all();
} catch (yii\base\InvalidConfigException $e) {
    if (strpos($e->getMessage(), 'The table does not exist') === 0) {
        // surface an actionable setup error
        throw new RuntimeException('Database not migrated: ' . $e->getMessage(), 0, $e);
    }
    throw $e;
}

Prevention

When it happens

Trigger: Using an AR class whose table was never created (migrations not run); tableName() has a typo or wrong {{%...}} table prefix; the model's getDb() points at a different database than the one holding the table; table name casing differs from the DDL on case-sensitive filesystems (Linux).

Common situations: Fresh environment where migrations were skipped; moving between environments with different tablePrefix config; stale schema cache after the table was created or renamed (enableSchemaCache on); selecting the wrong 'db' component in a multi-database app.

Related errors

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