mybatis/mybatis-3 · error · TypeException

The alias '{}' is already mapped to the value '{}'.

Error message

The alias '{}' is already mapped to the value '{}'.

What it means

Aliases are unique per registry (keyed by lower-cased name). registerAlias throws this TypeException when the key already maps to a DIFFERENT class than the one being registered — re-registering the same class is allowed, mapping a second class onto an existing alias is not.

Source

Thrown at src/main/java/org/apache/ibatis/type/TypeAliasRegistry.java:164

  }

  public void registerAlias(Class<?> type) {
    String alias = type.getSimpleName();
    Alias aliasAnnotation = type.getAnnotation(Alias.class);
    if (aliasAnnotation != null) {
      alias = aliasAnnotation.value();
    }
    registerAlias(alias, type);
  }

  public void registerAlias(String alias, Class<?> value) {
    if (alias == null) {
      throw new TypeException("The parameter alias cannot be null");
    }
    // issue #748
    String key = alias.toLowerCase(Locale.ENGLISH);
    if (typeAliases.containsKey(key) && typeAliases.get(key) != null && !typeAliases.get(key).equals(value)) {
      throw new TypeException(
          "The alias '" + alias + "' is already mapped to the value '" + typeAliases.get(key).getName() + "'.");
    }
    typeAliases.put(key, value);
  }

  public void registerAlias(String alias, String value) {
    try {
      registerAlias(alias, Resources.classForName(value));
    } catch (ClassNotFoundException e) {
      throw new TypeException("Error registering type alias " + alias + " for " + value + ". Cause: " + e, e);
    }
  }

  /**
   * Gets the type aliases.
   *
   * @return the type aliases
   *

View on GitHub (pinned to 008069adb1)

Solutions

1. Give one class an explicit distinct alias via @Alias("apiUser") on the class
2. Narrow the scanned packages so only one same-named class is picked up
3. Register the colliding class under its fully-qualified name instead of an alias

Example fix

// before
package com.example.api; public class User {} // collides with com.example.User after package scan

// after
@Alias("apiUser")
package com.example.api; public class User {}

Map<String, Class<?>> existing = configuration.getTypeAliasRegistry().getTypeAliases();
String key = alias.toLowerCase(Locale.ROOT);
if (existing.containsKey(key) && !existing.get(key).equals(type)) {
  throw new IllegalStateException("Alias '" + alias + "' already bound to " + existing.get(key).getName());
}

When it happens

Trigger: Package-scanning two packages that each contain a class with the same simple name (e.g. two User classes); registering a class whose simple name collides with a built-in alias; hand-registering an alias already used by another type.

Common situations: Scanning broad packages like com.example and com.example.api that share DTO names; merging modules that both define Customer; attempting to override built-in aliases such as 'integer' or 'date'.

Related errors

• Error resolving class. Cause: {cause}
• Could not resolve type alias '{}'. Cause: {}
• The parameter alias cannot be null
• Error registering type alias {} for {}. Cause: {}
• Unknown execution method for: {name}

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/58f0fec13aa0d2b5. Report an issue: GitHub.