apache/shardingsphere · error · AmbiguousIdentifierException

23

23

Error message

Identifier '%s' is ambiguous, matched actual identifiers: %s.

What it means

Error "Identifier '%s' is ambiguous, matched actual identifiers: %s." thrown in apache/shardingsphere.

Source

Thrown at infra/common/src/main/java/org/apache/shardingsphere/infra/metadata/identifier/IdentifierIndex.java:207

        NormalizedBucket<T> normalizedBucket = currentSnapshot.getNormalizedBuckets().get(policy.normalizeForLookup(identifier));
        if (null == normalizedBucket) {
            return null;
        }
        return getByUnquotedNormalizedIdentifier(currentSnapshot, normalizedBucket, identifier);
    }
    
    private T getByUnquotedNormalizedIdentifier(final Snapshot<T> currentSnapshot, final NormalizedBucket<T> normalizedBucket, final String identifier) {
        if (!normalizedBucket.hasUnquotedIdentifier()) {
            return null;
        }
        if (normalizedBucket.hasSingleUnquotedIdentifier()) {
            return normalizedBucket.getSingleUnquotedValue();
        }
        T exactMatchedValue = findExactMatchedValue(currentSnapshot.getExactValues(), normalizedBucket.getUnquotedIdentifiers(), identifier);
        if (null != exactMatchedValue) {
            return exactMatchedValue;
        }
        throw new AmbiguousIdentifierException(identifier, normalizedBucket.getUnquotedIdentifiers());
    }
    
    private Optional<T> findByQuotedNormalizedIdentifier(final Snapshot<T> currentSnapshot, final IdentifierCasePolicy policy, final IdentifierValue identifierValue) {
        NormalizedBucket<T> normalizedBucket = currentSnapshot.getNormalizedBuckets().get(policy.normalizeForLookup(identifierValue.getValue()));
        if (null == normalizedBucket) {
            return Optional.empty();
        }
        if (normalizedBucket.hasSingleIdentifier()) {
            return policy.matches(normalizedBucket.getSingleIdentifier(), identifierValue.getValue(), identifierValue.getQuoteCharacter())
                    ? Optional.ofNullable(normalizedBucket.getSingleValue())
                    : Optional.empty();
        }
        String matchedIdentifier = null;
        Collection<String> ambiguousIdentifiers = null;
        for (String each : normalizedBucket.getIdentifiers()) {
            if (!policy.matches(each, identifierValue.getValue(), identifierValue.getQuoteCharacter())) {
                continue;
            }

View on GitHub (pinned to e952770a21)

Solutions

1. Qualify the identifier with its schema or table so the lookup is unambiguous.
2. Use the exact case-sensitive identifier or quote the identifier if it was created with quotes.
3. Rename one of the colliding actual identifiers so names do not overlap.

When it happens

Trigger: An unqualified column or identifier matches more than one actual table or column during metadata lookup in IdentifierIndex.

Common situations: Ambiguous column references in joins or subqueries where several tables contain the same column name; case-mismatched unquoted identifiers.

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/efae34b6f8521a37. Report an issue: GitHub.