phalcon/cphalcon · error · Phalcon\Db\Exceptions\TableMustHaveColumn

The table must contain at least one column

Error message

The table must contain at least one column

What it means

createTable() requires the $definition array to contain a 'columns' key. The guard '!fetch columns, definition["columns"]' throws TableMustHaveColumn when the key is entirely absent. The columns entry must be a non-empty array of Phalcon\Db\Column (ColumnInterface) objects describing each field.

Source

Thrown at phalcon/Db/Adapter/AbstractAdapter.zep:324

        if unlikely !dialect->supportsSavePoints() {
            throw new SavepointsNotSupported();
        }

        return this->{"execute"}(
            dialect->createSavepoint(name)
        );
    }

    /**
     * Creates a table
     */
    public function createTable( string tableName,  string schemaName,  array definition) -> bool
    {
        var columns;

        if unlikely !fetch columns, definition["columns"] {
            throw new TableMustHaveColumn();
        }

        if unlikely empty columns {
            throw new TableMustHaveColumn();
        }

        return this->{"execute"}(
            this->dialect->createTable(
                tableName,
                schemaName,
                definition
            )
        );
    }

    /**
     * Creates a view
     */

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add a 'columns' key with Phalcon\Db\Column objects: ['columns' => [new Column('id', ['type' => Column::TYPE_INTEGER, 'primary' => true]), ...]]
2. If the definition is built dynamically, assert isset($definition['columns']) before calling createTable()
3. Check the key spelling: it must be exactly 'columns'

Example fix

// before
$db->createTable('users', null, ['indexes' => $indexes]);

// after
$db->createTable('users', null, [
    'columns' => [
        new Column('id',   ['type' => Column::TYPE_INTEGER, 'primary' => true]),
        new Column('name', ['type' => Column::TYPE_VARCHAR, 'size' => 100]),
    ],
    'indexes' => $indexes,
]);

if (!isset($definition['columns'])) {
    throw new InvalidArgumentException('createTable definition needs a "columns" key');
}
$db->createTable($table, $schema, $definition);

When it happens

Trigger: $db->createTable('users', null, ['indexes' => [...]]), ['columns' => ...] omitted; building the definition array dynamically and the columns branch never executes; typo 'column' or 'fileds'/'collumns' as the key name.

Common situations: Programmatic schema builders that assemble definition parts conditionally; migrations ported from other tools where the columns block lives elsewhere; copy-paste from createIndex/addColumn examples that omit columns.

Related errors

• The 'dialectClass' '{className}' must implement Phalcon\Db\D
• Savepoints are not supported by this database adapter
• Unable to insert into {table} without data
• Nested transaction with savepoints behavior cannot be change
• The number of values in the update is not the same as fields

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/352de2ffd2a7cf77. Report an issue: GitHub.