doctrine/orm · error · QueryException

Undefined reference field mapping "%s"

Error message

Undefined reference field mapping "%s"

What it means

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).

Source

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

    public string|null $fieldMapping = null;

    public function getSql(SqlWalker $sqlWalker): string
    {
        assert($this->pathExpression->field !== null);
        $entityManager = $sqlWalker->getEntityManager();
        $platform      = $entityManager->getConnection()->getDatabasePlatform();
        $quoteStrategy = $entityManager->getConfiguration()->getQuoteStrategy();
        $dqlAlias      = $this->pathExpression->identificationVariable;
        $assocField    = $this->pathExpression->field;
        $assoc         = $sqlWalker->getMetadataForDqlAlias($dqlAlias)->associationMappings[$assocField];
        $targetEntity  = $entityManager->getClassMetadata($assoc->targetEntity);

        assert($assoc->isToOneOwningSide());
        $joinColumn = reset($assoc->joinColumns);

        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));
            }
        }

View on GitHub (pinned to d9b9ff7301)

Solutions

1. Pass a persistent field name of the TARGET entity: IDENTITY(o.customer, 'id')
2. Omit the second argument when the association has a single join column — IDENTITY(o.customer) uses reset($assoc->joinColumns)
3. Run the query in a test: the error surfaces at getSql() time before hitting the database

Example fix

-- before
SELECT IDENTITY(o.customer, 'customer_id') FROM App\Entity\Order o
-- after
SELECT IDENTITY(o.customer, 'id') FROM App\Entity\Order o
-- or simply:
SELECT IDENTITY(o.customer) FROM App\Entity\Order o

$targetMeta = $em->getClassMetadata($sourceMeta->getAssociationMapping($assocField)->targetEntity);
if ($field !== null && ! isset($targetMeta->fieldMappings[$field])) {
    throw new InvalidArgumentException("IDENTITY(): '$field' is not a mapped field of {$targetMeta->name}");
}

function isTargetFieldMapped(ClassMetadata $targetMeta, string $field): bool
{
    return isset($targetMeta->fieldMappings[$field]);
}

When it happens

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

Common situations: Confusing column names with field names; composite-FK associations where the developer guesses the identifier field name; refactoring entity fields without updating IDENTITY() calls.

Related errors

• Unable to resolve the 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/31df5dfb0f735c91. Report an issue: GitHub.