{"record":{"id":"58f0fec13aa0d2b5","repo":"mybatis/mybatis-3","slug":"the-alias-is-already-mapped-to-the-value","errorCode":null,"errorMessage":"The alias '{}' is already mapped to the value '{}'.","messagePattern":"The alias '(.+?)' is already mapped to the value '(.+?)'\\.","errorType":"exception","errorClass":"TypeException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/type/TypeAliasRegistry.java","lineNumber":164,"sourceCode":"  }\n\n  public void registerAlias(Class<?> type) {\n    String alias = type.getSimpleName();\n    Alias aliasAnnotation = type.getAnnotation(Alias.class);\n    if (aliasAnnotation != null) {\n      alias = aliasAnnotation.value();\n    }\n    registerAlias(alias, type);\n  }\n\n  public void registerAlias(String alias, Class<?> value) {\n    if (alias == null) {\n      throw new TypeException(\"The parameter alias cannot be null\");\n    }\n    // issue #748\n    String key = alias.toLowerCase(Locale.ENGLISH);\n    if (typeAliases.containsKey(key) && typeAliases.get(key) != null && !typeAliases.get(key).equals(value)) {\n      throw new TypeException(\n          \"The alias '\" + alias + \"' is already mapped to the value '\" + typeAliases.get(key).getName() + \"'.\");\n    }\n    typeAliases.put(key, value);\n  }\n\n  public void registerAlias(String alias, String value) {\n    try {\n      registerAlias(alias, Resources.classForName(value));\n    } catch (ClassNotFoundException e) {\n      throw new TypeException(\"Error registering type alias \" + alias + \" for \" + value + \". Cause: \" + e, e);\n    }\n  }\n\n  /**\n   * Gets the type aliases.\n   *\n   * @return the type aliases\n   *","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/type/TypeAliasRegistry.java#L146-L182","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Give one class an explicit distinct alias via @Alias(\"apiUser\") on the class","Narrow the scanned packages so only one same-named class is picked up","Register the colliding class under its fully-qualified name instead of an alias"],"exampleFix":"// before\npackage com.example.api; public class User {} // collides with com.example.User after package scan\n\n// after\n@Alias(\"apiUser\")\npackage com.example.api; public class User {}","handlingStrategy":"validation","validationCode":"Map<String, Class<?>> existing = configuration.getTypeAliasRegistry().getTypeAliases();\nString key = alias.toLowerCase(Locale.ROOT);\nif (existing.containsKey(key) && !existing.get(key).equals(type)) {\n  throw new IllegalStateException(\"Alias '\" + alias + \"' already bound to \" + existing.get(key).getName());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use @Alias to give globally unique aliases to same-named classes","Scan the narrowest packages possible","Add a startup assertion that all registered aliases are unique across modules"],"tags":["mybatis","type-alias","naming-conflict","package-scan"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}