doctrine/orm · error · QueryException

Unable to resolve the reference field mapping "%s"

Error message

Unable to resolve the reference field mapping "%s"

What it means

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.

Source

Thrown at src/Query/AST/Functions/IdentityFunction.php:59

        if ($this->fieldMapping !== null) {
            if (! isset($targetEntity->fieldMappings[$this->fieldMapping])) {
                throw new QueryException(sprintf('Undefined reference field mapping "%s"', $this->fieldMapping));
            }

            $field      = $targetEntity->fieldMappings[$this->fieldMapping];
            $joinColumn = null;

            foreach ($assoc->joinColumns as $mapping) {
                if ($mapping->referencedColumnName === $field->columnName) {
                    $joinColumn = $mapping;

                    break;
                }
            }

            if ($joinColumn === null) {
                throw new QueryException(sprintf('Unable to resolve the reference field mapping "%s"', $this->fieldMapping));
            }
        }

        // The table with the relation may be a subclass, so get the table name from the association definition
        $tableName = $entityManager->getClassMetadata($assoc->sourceEntity)->getTableName();

        $tableAlias = $sqlWalker->getSQLTableAlias($tableName, $dqlAlias);
        $columnName = $quoteStrategy->getJoinColumnName($joinColumn, $targetEntity, $platform);

        return $tableAlias . '.' . $columnName;
    }

    public function parse(Parser $parser): void
    {
        $parser->match(TokenType::T_IDENTIFIER);
        $parser->match(TokenType::T_OPEN_PARENTHESIS);

        $this->pathExpression = $parser->SingleValuedAssociationPathExpression();

View on GitHub (pinned to d9b9ff7301)

Solutions

1. Pass the field whose column IS the referencedColumnName of a join column (usually the target identifier field)
2. Or change the association so a join column references the wanted column: #[JoinColumn(referencedColumnName: 'externalRef')]
3. Omit the second argument for single-join-column associations

Example fix

-- before
-- #[JoinColumn(referencedColumnName: 'id')]
SELECT IDENTITY(o.customer, 'externalRef') FROM App\Entity\Order o
-- after
SELECT IDENTITY(o.customer, 'id') FROM App\Entity\Order o

$assoc = $sourceMeta->getAssociationMapping($assocField);
$targetMeta = $em->getClassMetadata($assoc->targetEntity);
$resolvable = false;
foreach ($assoc->joinColumns as $jc) {
    if ($targetMeta->fieldMappings[$field]->columnName === $jc->referencedColumnName) { $resolvable = true; break; }
}
if (! $resolvable) { /* pick the identifier field or fix referencedColumnName */ }

When it happens

Trigger: 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.

Common situations: Composite or non-default foreign keys; refactoring referencedColumnName on associations without updating DQL; referencing unique-but-not-referenced target columns.

Related errors

• Undefined reference field mapping "%s"
• {argAlias} does not exist
• The hint "HINT_CACHE_EVICT" is not valid for select statemen
• Expression of type '%s' not allowed in this context.
• No metadata for DQL alias: %s

AI-assisted analysis of doctrine/orm@d9b9ff7301 (2026-08-21). Data as JSON: /api/errors/8ef44eeedc0b694a. Report an issue: GitHub.