{"record":{"id":"a7d457e18d871a00","repo":"mybatis/mybatis-3","slug":"error-registering-type-alias-for-cause","errorCode":null,"errorMessage":"Error registering type alias {} for {}. Cause: {}","messagePattern":"Error registering type alias (.+?) for (.+?)\\. Cause: (.+?)","errorType":"exception","errorClass":"TypeException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/type/TypeAliasRegistry.java","lineNumber":174,"sourceCode":"\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   *\n   * @since 3.2.2\n   */\n  public Map<String, Class<?>> getTypeAliases() {\n    return Map.copyOf(typeAliases);\n  }\n\n}\n","sourceCodeStart":156,"sourceCodeEnd":190,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/type/TypeAliasRegistry.java#L156-L190","documentation":"The string-based registerAlias(alias, value) overload resolves the value with Resources.classForName before delegating to the Class-based overload. A ClassNotFoundException there is wrapped in this TypeException naming the alias and the un-loadable class string.","triggerScenarios":"<typeAlias alias=\"user\" type=\"com.example.Usr\"/> in mybatis-config.xml where the type attribute has a typo, wrong package, or the class is missing from the classpath; programmatic registerAlias(\"user\", \"com.example.User\") with the same problems.","commonSituations":"Renaming/moving classes without updating XML configuration; incomplete dependencies (class exists in IDE but not in the packaged app); typos in the type attribute.","solutions":["Correct the fully-qualified class name in the type attribute / value string","Ensure the class is packaged (check the jar/war contents or dependency scope)","Prefer the Class-based overload registerAlias(\"user\", User.class) so mistakes become compile-time errors"],"exampleFix":"// before\n<typeAlias alias=\"user\" type=\"com.example.Usr\"/>\n\n// after\n<typeAlias alias=\"user\" type=\"com.example.User\"/>","handlingStrategy":"validation","validationCode":"try {\n  Class<?> clazz = Class.forName(typeName);\n  configuration.getTypeAliasRegistry().registerAlias(alias, clazz);\n} catch (ClassNotFoundException e) {\n  throw new IllegalStateException(\"Alias target not on classpath: \" + typeName, e);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the Class-based registration overload so typos fail at compile time","Validate all <typeAlias> entries at boot with Class.forName before MyBatis parses mappers"],"tags":["mybatis","type-alias","classpath","configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}