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

Foreign key columns are required

Error message

Foreign key columns are required

What it means

The second required-key check in Phalcon\Db\Reference::__construct(): after 'referencedTable', the definition must contain 'columns' listing the local foreign-key columns. If it is missing, ForeignKeyColumnsRequired is thrown because the constraint has no local side to apply.

Source

Thrown at phalcon/Db/Reference.zep:114

    /**
     * Phalcon\Db\Reference constructor
     */
    public function __construct( string name,  array definition)
    {
        var columns, schema, referencedTable, referencedSchema,
            referencedColumns, onDelete, onUpdate;

        let this->name = name;

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

        let this->referencedTable = referencedTable;

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

        let this->columns = columns;

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

        let this->referencedColumns = referencedColumns;

        if fetch schema, definition["schema"] {
            let this->schemaName = schema;
        }

        if fetch referencedSchema, definition["referencedSchema"] {
            let this->referencedSchema = referencedSchema;
        }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add 'columns' => ['user_id'] naming the local column(s)
2. Validate all three required keys with one isset() guard before constructing
3. Check the migration/config source that produced the definition

Example fix

// before
new Reference('fk_posts_user', [
    'referencedTable' => 'users',
    'referencedColumns' => ['id'],
]);

// after
new Reference('fk_posts_user', [
    'columns' => ['user_id'],
    'referencedTable' => 'users',
    'referencedColumns' => ['id'],
]);

if (!isset($definition['referencedTable'], $definition['columns'], $definition['referencedColumns'])) {
    throw new InvalidArgumentException(
        'Reference definition requires referencedTable, columns and referencedColumns'
    );
}
$reference = new \Phalcon\Db\Reference('fk_posts_user', $definition);

function isCompleteReferenceDefinition(array $definition): bool
{
    return isset($definition['referencedTable'], $definition['columns'], $definition['referencedColumns']);
}

try {
    $reference = new \Phalcon\Db\Reference('fk_posts_user', $definition);
} catch (\Phalcon\Db\Exceptions\ForeignKeyColumnsRequired $e) {
    throw new InvalidArgumentException('Foreign key definition is missing local columns', 0, $e);
}

When it happens

Trigger: new Reference('fk_posts_user', ['referencedTable' => 'users', 'referencedColumns' => ['id']]) without 'columns'; the local columns key dropped during refactoring or lost when definitions were copied from config.

Common situations: Migration definitions hand-written from memory (only the target side specified); generators that emit referencedTable/referencedColumns but skip local columns; key renamed to 'localColumns'.

Related errors

• Referenced table is required
• Referenced columns of the foreign key are required
• Dropping a foreign key constraint is not supported by SQLite
• Index definition 'columns' key must be an array
• Index definition 'directions' key must be an array

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