mybatis/mybatis-3 · error · TypeException

Error registering type alias {} for {}. Cause: {}

Error message

Error registering type alias {} for {}. Cause: {}

What it means

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.

Source

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

  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
   *
   * @since 3.2.2
   */
  public Map<String, Class<?>> getTypeAliases() {
    return Map.copyOf(typeAliases);
  }

}

View on GitHub (pinned to 008069adb1)

Solutions

1. Correct the fully-qualified class name in the type attribute / value string
2. Ensure the class is packaged (check the jar/war contents or dependency scope)
3. Prefer the Class-based overload registerAlias("user", User.class) so mistakes become compile-time errors

Example fix

// before
<typeAlias alias="user" type="com.example.Usr"/>

// after
<typeAlias alias="user" type="com.example.User"/>

try {
  Class<?> clazz = Class.forName(typeName);
  configuration.getTypeAliasRegistry().registerAlias(alias, clazz);
} catch (ClassNotFoundException e) {
  throw new IllegalStateException("Alias target not on classpath: " + typeName, e);
}

When it happens

Trigger: <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.

Common situations: Renaming/moving classes without updating XML configuration; incomplete dependencies (class exists in IDE but not in the packaged app); typos in the type attribute.

Related errors

• Could not resolve type alias '{}'. Cause: {}
• Error resolving class. Cause: {cause}
• Error setting driver on UnpooledDataSource.
• Cannot find class: {}
• Could not find resource {}

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