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

Referenced columns of the foreign key are required

Error message

Referenced columns of the foreign key are required

What it means

The third required-key check in Phalcon\Db\Reference::__construct(): the definition must contain 'referencedColumns' listing the referenced (target) columns, matching the local 'columns' one-to-one. If it is missing, ReferencedColumnsRequired is thrown because the constraint has no target side.

Source

Thrown at phalcon/Db/Reference.zep:120

        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;
        }

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

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

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add 'referencedColumns' => ['id'] with one entry per local column
2. Validate isset($definition['referencedColumns']) && count matches count($definition['columns']) before constructing
3. Fix the definition source in migrations/config

Example fix

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

// 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'
    );
}
if (count($definition['columns']) !== count($definition['referencedColumns'])) {
    throw new InvalidArgumentException('columns and referencedColumns must match one-to-one');
}
$reference = new \Phalcon\Db\Reference('fk_posts_user', $definition);

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

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

When it happens

Trigger: new Reference('fk_posts_user', ['columns' => ['user_id'], 'referencedTable' => 'users']) without 'referencedColumns'; the key typo'd as 'referenced_fields'; definitions built by joining two config fragments where the target columns piece was skipped.

Common situations: Assuming the referenced primary key is implied (it is not — Phalcon requires it explicitly); copy-paste from an index definition (which has no referenced side); incomplete migration generators.

Related errors

• Referenced table is required
• Foreign key columns 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/b4ba74446895654e. Report an issue: GitHub.