{"record":{"id":"b4ba74446895654e","repo":"phalcon/cphalcon","slug":"referenced-columns-of-the-foreign-key-are-required","errorCode":null,"errorMessage":"Referenced columns of the foreign key are required","messagePattern":"Referenced columns of the foreign key are required","errorType":"exception","errorClass":"Phalcon\\Db\\Exceptions\\ReferencedColumnsRequired","httpStatus":null,"severity":"error","filePath":"phalcon/Db/Reference.zep","lineNumber":120,"sourceCode":"        var columns, schema, referencedTable, referencedSchema,\n            referencedColumns, onDelete, onUpdate;\n\n        let this->name = name;\n\n        if unlikely !fetch referencedTable, definition[\"referencedTable\"] {\n            throw new ReferencedTableRequired();\n        }\n\n        let this->referencedTable = referencedTable;\n\n        if unlikely !fetch columns, definition[\"columns\"] {\n            throw new ForeignKeyColumnsRequired();\n        }\n\n        let this->columns = columns;\n\n        if unlikely !fetch referencedColumns, definition[\"referencedColumns\"] {\n            throw new ReferencedColumnsRequired();\n        }\n\n        let this->referencedColumns = referencedColumns;\n\n        if fetch schema, definition[\"schema\"] {\n            let this->schemaName = schema;\n        }\n\n        if fetch referencedSchema, definition[\"referencedSchema\"] {\n            let this->referencedSchema = referencedSchema;\n        }\n\n        if fetch onDelete, definition[\"onDelete\"] {\n            let this->onDelete = onDelete;\n        }\n\n        if fetch onUpdate, definition[\"onUpdate\"] {\n            let this->onUpdate = onUpdate;","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Db/Reference.zep#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add 'referencedColumns' => ['id'] with one entry per local column","Validate isset($definition['referencedColumns']) && count matches count($definition['columns']) before constructing","Fix the definition source in migrations/config"],"exampleFix":"// before\nnew Reference('fk_posts_user', [\n    'columns' => ['user_id'],\n    'referencedTable' => 'users',\n]);\n\n// after\nnew Reference('fk_posts_user', [\n    'columns' => ['user_id'],\n    'referencedTable' => 'users',\n    'referencedColumns' => ['id'],\n]);","handlingStrategy":"validation","validationCode":"if (!isset($definition['referencedTable'], $definition['columns'], $definition['referencedColumns'])) {\n    throw new InvalidArgumentException(\n        'Reference definition requires referencedTable, columns and referencedColumns'\n    );\n}\nif (count($definition['columns']) !== count($definition['referencedColumns'])) {\n    throw new InvalidArgumentException('columns and referencedColumns must match one-to-one');\n}\n$reference = new \\Phalcon\\Db\\Reference('fk_posts_user', $definition);","typeGuard":"function isCompleteReferenceDefinition(array $definition): bool\n{\n    return isset($definition['referencedTable'], $definition['columns'], $definition['referencedColumns'])\n        && is_array($definition['columns'])\n        && is_array($definition['referencedColumns']);\n}","tryCatchPattern":"try {\n    $reference = new \\Phalcon\\Db\\Reference('fk_posts_user', $definition);\n} catch (\\Phalcon\\Db\\Exceptions\\ReferencedColumnsRequired $e) {\n    throw new InvalidArgumentException('Foreign key definition is missing referencedColumns', 0, $e);\n}","preventionTips":["Phalcon does not infer the referenced primary key — always state 'referencedColumns' explicitly","Keep local and referenced column lists the same length and order","Check for the exact key spelling 'referencedColumns' when definitions come from config"],"tags":["phalcon-db","foreign-key","reference","schema-definition","migrations"],"backgroundTag":"missing-definition-key","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}