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

Referenced table is required

Error message

Referenced table is required

What it means

Phalcon\Db\Reference models a foreign key for DDL generation. Its constructor validates the definition array in order and requires 'referencedTable' first; when that key is absent, ReferencedTableRequired is thrown. A foreign key with no target table cannot be expressed in SQL.

Source

Thrown at phalcon/Db/Reference.zep:108

    /**
     * ON UPDATE
     *
     * @var string
     */
    protected onUpdate;

    /**
     * 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;

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add the key: 'referencedTable' => 'users' alongside 'columns' and 'referencedColumns'
2. Validate isset($definition['referencedTable'], $definition['columns'], $definition['referencedColumns']) before constructing
3. Fix the config/migration source that produced the incomplete definition

Example fix

// before
new Reference('fk_posts_user', [
    'columns' => ['user_id'],
    '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\ReferencedTableRequired $e) {
    throw new InvalidArgumentException('Foreign key definition is missing referencedTable', 0, $e);
}

When it happens

Trigger: new Reference('fk_posts_user', ['columns' => ['user_id'], 'referencedColumns' => ['id']]) missing 'referencedTable'; typo'd keys such as 'referenceTable' or 'referenced_table'; definitions loaded from config where the target table entry was omitted.

Common situations: Migration generators emitting partial definitions; renaming the target table without updating FK definitions; copy-pasting an existing Reference and dropping the key by mistake.

Related errors

• Foreign key columns are 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/95fd2ad4bf7f746d. Report an issue: GitHub.