{"record":{"id":"31df5dfb0f735c91","repo":"doctrine/orm","slug":"undefined-reference-field-mapping-s","errorCode":null,"errorMessage":"Undefined reference field mapping \"%s\"","messagePattern":"Undefined reference field mapping \"(.+?)\"","errorType":"exception","errorClass":"QueryException","httpStatus":null,"severity":"error","filePath":"src/Query/AST/Functions/IdentityFunction.php","lineNumber":44,"sourceCode":"    public string|null $fieldMapping = null;\n\n    public function getSql(SqlWalker $sqlWalker): string\n    {\n        assert($this->pathExpression->field !== null);\n        $entityManager = $sqlWalker->getEntityManager();\n        $platform      = $entityManager->getConnection()->getDatabasePlatform();\n        $quoteStrategy = $entityManager->getConfiguration()->getQuoteStrategy();\n        $dqlAlias      = $this->pathExpression->identificationVariable;\n        $assocField    = $this->pathExpression->field;\n        $assoc         = $sqlWalker->getMetadataForDqlAlias($dqlAlias)->associationMappings[$assocField];\n        $targetEntity  = $entityManager->getClassMetadata($assoc->targetEntity);\n\n        assert($assoc->isToOneOwningSide());\n        $joinColumn = reset($assoc->joinColumns);\n\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","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/doctrine/orm/blob/d9b9ff73016bf598ae07515f97289ce8074e97a5/src/Query/AST/Functions/IdentityFunction.php#L26-L62","documentation":"The DQL IDENTITY(assoc, 'field') function selects the FK value of a to-one association; the optional second argument names which reference field of the TARGET entity's column to use. IdentityFunction::getSql() looks that name up in the target entity's fieldMappings and throws a QueryException if it is not a persistent field of the target class (note: it takes FIELD names, not column names).","triggerScenarios":"DQL like SELECT IDENTITY(o.customer, 'customer_id') FROM Order o where 'customer_id' is a column name or an unmapped property of Customer; typo in the field name; referencing a field of the SOURCE entity instead of the target.","commonSituations":"Confusing column names with field names; composite-FK associations where the developer guesses the identifier field name; refactoring entity fields without updating IDENTITY() calls.","solutions":["Pass a persistent field name of the TARGET entity: IDENTITY(o.customer, 'id')","Omit the second argument when the association has a single join column — IDENTITY(o.customer) uses reset($assoc->joinColumns)","Run the query in a test: the error surfaces at getSql() time before hitting the database"],"exampleFix":"-- before\nSELECT IDENTITY(o.customer, 'customer_id') FROM App\\Entity\\Order o\n-- after\nSELECT IDENTITY(o.customer, 'id') FROM App\\Entity\\Order o\n-- or simply:\nSELECT IDENTITY(o.customer) FROM App\\Entity\\Order o","handlingStrategy":"validation","validationCode":"$targetMeta = $em->getClassMetadata($sourceMeta->getAssociationMapping($assocField)->targetEntity);\nif ($field !== null && ! isset($targetMeta->fieldMappings[$field])) {\n    throw new InvalidArgumentException(\"IDENTITY(): '$field' is not a mapped field of {$targetMeta->name}\");\n}","typeGuard":"function isTargetFieldMapped(ClassMetadata $targetMeta, string $field): bool\n{\n    return isset($targetMeta->fieldMappings[$field]);\n}","tryCatchPattern":null,"preventionTips":["Use target-entity FIELD names in IDENTITY(), never column names","Omit the second argument for single join-column associations","Compile DQL strings in unit tests to catch mapping errors early"],"tags":["dql","identity-function","field-mapping","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"}