{"record":{"id":"8ef44eeedc0b694a","repo":"doctrine/orm","slug":"unable-to-resolve-the-reference-field-mapping-s","errorCode":null,"errorMessage":"Unable to resolve the reference field mapping \"%s\"","messagePattern":"Unable to resolve the reference field mapping \"(.+?)\"","errorType":"exception","errorClass":"QueryException","httpStatus":null,"severity":"error","filePath":"src/Query/AST/Functions/IdentityFunction.php","lineNumber":59,"sourceCode":"\n        if ($this->fieldMapping !== null) {\n            if (! isset($targetEntity->fieldMappings[$this->fieldMapping])) {\n                throw new QueryException(sprintf('Undefined reference field mapping \"%s\"', $this->fieldMapping));\n            }\n\n            $field      = $targetEntity->fieldMappings[$this->fieldMapping];\n            $joinColumn = null;\n\n            foreach ($assoc->joinColumns as $mapping) {\n                if ($mapping->referencedColumnName === $field->columnName) {\n                    $joinColumn = $mapping;\n\n                    break;\n                }\n            }\n\n            if ($joinColumn === null) {\n                throw new QueryException(sprintf('Unable to resolve the reference field mapping \"%s\"', $this->fieldMapping));\n            }\n        }\n\n        // The table with the relation may be a subclass, so get the table name from the association definition\n        $tableName = $entityManager->getClassMetadata($assoc->sourceEntity)->getTableName();\n\n        $tableAlias = $sqlWalker->getSQLTableAlias($tableName, $dqlAlias);\n        $columnName = $quoteStrategy->getJoinColumnName($joinColumn, $targetEntity, $platform);\n\n        return $tableAlias . '.' . $columnName;\n    }\n\n    public function parse(Parser $parser): void\n    {\n        $parser->match(TokenType::T_IDENTIFIER);\n        $parser->match(TokenType::T_OPEN_PARENTHESIS);\n\n        $this->pathExpression = $parser->SingleValuedAssociationPathExpression();","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/doctrine/orm/blob/d9b9ff73016bf598ae07515f97289ce8074e97a5/src/Query/AST/Functions/IdentityFunction.php#L41-L77","documentation":"When IDENTITY(assoc, 'field') is given a second argument, IdentityFunction::getSql() must find a join column on the association whose referencedColumnName equals the named field's columnName — that is the FK-to-target-column pairing. If the field exists on the target entity but none of the association's joinColumns reference it, the loop leaves $joinColumn null and the QueryException 'Unable to resolve the reference field mapping' is thrown.","triggerScenarios":"IDENTITY(o.customer, 'externalRef') where externalRef is a real field of Customer but the association's @JoinColumn(referencedColumnName: ...) points at 'id' (the default), so no join column pairs with externalRef's column.","commonSituations":"Composite or non-default foreign keys; refactoring referencedColumnName on associations without updating DQL; referencing unique-but-not-referenced target columns.","solutions":["Pass the field whose column IS the referencedColumnName of a join column (usually the target identifier field)","Or change the association so a join column references the wanted column: #[JoinColumn(referencedColumnName: 'externalRef')]","Omit the second argument for single-join-column associations"],"exampleFix":"-- before\n-- #[JoinColumn(referencedColumnName: 'id')]\nSELECT IDENTITY(o.customer, 'externalRef') FROM App\\Entity\\Order o\n-- after\nSELECT IDENTITY(o.customer, 'id') FROM App\\Entity\\Order o","handlingStrategy":"validation","validationCode":"$assoc = $sourceMeta->getAssociationMapping($assocField);\n$targetMeta = $em->getClassMetadata($assoc->targetEntity);\n$resolvable = false;\nforeach ($assoc->joinColumns as $jc) {\n    if ($targetMeta->fieldMappings[$field]->columnName === $jc->referencedColumnName) { $resolvable = true; break; }\n}\nif (! $resolvable) { /* pick the identifier field or fix referencedColumnName */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass the field whose column matches a join column's referencedColumnName (usually the identifier)","Keep #[JoinColumn(referencedColumnName)] and IDENTITY() second args in sync","Document composite-FK pairings next to the association"],"tags":["dql","identity-function","join-column","foreign-key"],"backgroundTag":"dql-invalid-field-reference","analyzedSha":"d9b9ff73016bf598ae07515f97289ce8074e97a5","analyzedAt":"2026-08-21T06:13:15.863Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}