mybatis/mybatis-3 · error · BuilderException

Error registering typeAlias for '{alias}'. Cause: {cause}

Error message

Error registering typeAlias for '{alias}'. Cause: {cause}

What it means

Error "Error registering typeAlias for '{alias}'. Cause: {cause}" thrown in mybatis/mybatis-3.

Source

Thrown at src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java:192

    if (context == null) {
      return;
    }
    for (XNode child : context.getChildren()) {
      if ("package".equals(child.getName())) {
        String typeAliasPackage = child.getStringAttribute("name");
        configuration.getTypeAliasRegistry().registerAliases(typeAliasPackage);
      } else {
        String alias = child.getStringAttribute("alias");
        String type = child.getStringAttribute("type");
        try {
          Class<?> clazz = Resources.classForName(type);
          if (alias == null) {
            typeAliasRegistry.registerAlias(clazz);
          } else {
            typeAliasRegistry.registerAlias(alias, clazz);
          }
        } catch (ClassNotFoundException e) {
          throw new BuilderException("Error registering typeAlias for '" + alias + "'. Cause: " + e, e);
        }
      }
    }
  }

  private void pluginsElement(XNode context) throws Exception {
    if (context != null) {
      for (XNode child : context.getChildren()) {
        String interceptor = child.getStringAttribute("interceptor");
        Properties properties = child.getChildrenAsProperties();
        Interceptor interceptorInstance = (Interceptor) resolveClass(interceptor).getDeclaredConstructor()
            .newInstance();
        interceptorInstance.setProperties(properties);
        configuration.addInterceptor(interceptorInstance);
      }
    }
  }

View on GitHub (pinned to 008069adb1)

Solutions

1. Inspect the nested cause; usually the aliased class cannot be loaded or the alias conflicts with an existing one.
2. Verify the class named in the typeAlias element exists on the classpath and is spelled correctly.
3. Choose a different alias if it collides with a built-in or previously registered alias.

When it happens

Trigger: Thrown at src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java:192 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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