mybatis/mybatis-3 · error · TypeException

Could not resolve type alias '{}'. Cause: {}

Error message

Could not resolve type alias '{}'.  Cause: {}

What it means

TypeAliasRegistry.resolveAlias lower-cases the input, checks the registered alias map, and as a last resort attempts Resources.classForName on the raw string. When both fail with ClassNotFoundException, it throws this TypeException: the string is neither a registered alias nor a loadable fully-qualified class name.

Source

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

  @SuppressWarnings("unchecked")
  // throws class cast exception as well if types cannot be assigned
  public <T> Class<T> resolveAlias(String string) {
    try {
      if (string == null) {
        return null;
      }
      // issue #748
      String key = string.toLowerCase(Locale.ENGLISH);
      Class<T> value;
      if (typeAliases.containsKey(key)) {
        value = (Class<T>) typeAliases.get(key);
      } else {
        value = (Class<T>) Resources.classForName(string);
      }
      return value;
    } catch (ClassNotFoundException e) {
      throw new TypeException("Could not resolve type alias '" + string + "'.  Cause: " + e, e);
    }
  }

  public void registerAliases(String packageName) {
    registerAliases(packageName, Object.class);
  }

  public void registerAliases(String packageName, Class<?> superType) {
    ResolverUtil<Class<?>> resolverUtil = new ResolverUtil<>();
    resolverUtil.find(new ResolverUtil.IsA(superType), packageName);
    Set<Class<? extends Class<?>>> typeSet = resolverUtil.getClasses();
    for (Class<?> type : typeSet) {
      // Ignore inner classes and interfaces (including package-info.java)
      // Skip also inner classes. See issue #6
      if (!type.isAnonymousClass() && !type.isInterface() && !type.isMemberClass()) {
        registerAlias(type);
      }
    }

View on GitHub (pinned to 008069adb1)

Solutions

1. Fix the alias spelling or use the fully-qualified class name
2. Register the class or its package: <typeAliases><package name="com.example.domain"/></typeAliases>
3. Verify the class is on the runtime classpath (dependency scope/classloader) when using a FQN

Example fix

// before
<typeAlias alias="usr" type="com.example.User"/> ... <select resultType="user">

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

String alias = "user";
Class<?> c = configuration.getTypeAliasRegistry().resolveAlias(alias); // throws early with clear message
// or pre-check: try { Class.forName(fqn); } catch (ClassNotFoundException e) { /* fix before boot */ }

try { ... resolveAlias(...) } catch (TypeException e) { // fail fast at startup with which alias is unknown; do not swallow }

When it happens

Trigger: A type/parameterType/resultType attribute like type="Usr" (typo), an alias that was never registered, or a fully-qualified class name whose class is not on the classpath (missing dependency, wrong package).

Common situations: Typos in mapper XML; moving classes to a new package without updating XML; forgetting to register a package (<typeAliases><package name="..."/></typeAliases>); fat-jar/classloader issues hiding domain classes.

Related errors

• Error registering type alias {} for {}. 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/a7c0a93bb944d3ec. Report an issue: GitHub.