baomidou/mybatis-plus · error · IllegalArgumentException

%s is ambiguous in %s (try using the full name including the

Error message

%s is ambiguous in %s (try using the full name including the namespace, or rename one of the entries)

What it means

Thrown by StrictMap.get when the value stored under a short key is the AMBIGUITY_INSTANCE sentinel. When useGeneratedShortKey is enabled, StrictMap stores a short name (text after the last dot) for each fully-qualified key; if two different full keys collapse to the same short name, the sentinel replaces the value and any later lookup by the short name throws this ambiguity error.

Source

Thrown at mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisConfiguration.java:485

            return super.put(key, value);
        }

        @Override
        public boolean containsKey(Object key) {
            if (key == null) {
                return false;
            }
            return super.get(key) != null;
        }

        @Override
        public V get(Object key) {
            V value = super.get(key);
            if (value == null) {
                throw new IllegalArgumentException(name + " does not contain value for " + key);
            }
            if (useGeneratedShortKey && AMBIGUITY_INSTANCE == value) {
                throw new IllegalArgumentException(key + " is ambiguous in " + name
                    + " (try using the full name including the namespace, or rename one of the entries)");
            }
            return value;
        }

        private String getShortName(String key) {
            final String[] keyParts = key.split("\\.");
            return keyParts[keyParts.length - 1];
        }
    }
}

View on GitHub (pinned to bf67d90747)

Solutions

Always reference statements by their full name including the namespace (e.g. com.example.UserMapper.selectById) instead of the short name, as the message suggests.
Rename one of the colliding statement ids so short names are unique.
Audit the error message key: it names the ambiguous short key; find all namespaces providing it and disambiguate callers.

Example fix

// before
List<User> users = sqlSession.selectList("selectById", 1);

// after
List<User> users = sqlSession.selectList("com.example.UserMapper.selectById", 1);

Defensive patterns

Strategy: validation

Validate before calling

// detect ambiguous short keys before use
class ShortKeyScan {
    static Set<String> ambiguous(Collection<String> ids) {
        Map<String, Integer> counts = new HashMap<>();
        ids.forEach(i -> counts.merge(i.substring(i.lastIndexOf('.') + 1), 1, Integer::sum));
        return counts.entrySet().stream().filter(e -> e.getValue() > 1)
            .map(Map.Entry::getKey).collect(java.util.stream.Collectors.toSet());
    }
}

Try / catch

Catch IllegalArgumentException matching "is ambiguous in"; extract the short key and switch the caller to the fully-qualified statement name.

Prevention

Always reference statements with the full namespace-qualified id.
Give multi-module mapper statements distinct ids, not just distinct namespaces.

When it happens

Trigger: Two mapped statements whose fully-qualified ids differ only in namespace but share the same trailing segment (e.g. com.a.UserMapper.selectById and com.b.UserMapper.selectById), then referencing the statement by its short name 'selectById'.

Common situations: Multiple modules each with a mapper containing identically-named statements; CRUD BaseMapper methods generating identical short ids across many mapper namespaces while some code path resolves by short name; copying mapper XML between modules without renaming ids.

Related errors

AI-assisted analysis of baomidou/mybatis-plus@bf67d90747 (2026-08-14). Data as JSON: /api/errors/0102188663d1e8a5. Report an issue: GitHub.