baomidou/mybatis-plus · error · BuilderException

Error registering typeAlias for

Error message

Error registering typeAlias for '%s'. Cause: %s

What it means

Thrown by typeAliasesElement when the class referenced by a <typeAlias type="..."/> entry cannot be loaded (ClassNotFoundException). The alias name is included in the message plus the CNFE cause, pinpointing exactly which registration failed.

Solutions

1. Fix the type attribute to the correct fully-qualified class name (copy from the actual class's package declaration).
2. If the class lives in another module/jar, add that artifact as a runtime dependency.
3. Prefer <package name="com.example.entity"/> bulk registration to avoid hand-written FQCNs, letting MyBatis scan the package.

Example fix

<!-- before -->
<typeAliases>
  <typeAlias alias="user" type="com.exmaple.entity.User"/>
</typeAliases>

<!-- after -->
<typeAliases>
  <typeAlias alias="user" type="com.example.entity.User"/>
</typeAliases>

// verify typeAlias classes are loadable before parsing
for (String fqcn : List.of("com.example.entity.User")) {
    Class.forName(fqcn); // throws early with the exact class name
}

Catch BuilderException starting 'Error registering typeAlias for'; the alias and CNFE cause name the offending entry — fix the FQCN in XML.

When it happens

Trigger: <typeAlias alias="user" type="com.exmaple.User"/> where the class does not exist on the classpath (typo, wrong package, missing dependency).

Common situations: Package renamed during refactoring while the XML kept the old FQCN; entity class moved to another module not on the runtime classpath; simple typographical errors in the type attribute.

Related errors

• A mapper element may only specify a url, resource or class…
• Cannot use both value() and name() attribute in the…
• Could not find a statement annotation that correspond a…
• Detected conflicting annotations
• Environment requires an id attribute.

AI-assisted analysis of baomidou/mybatis-plus@bf67d90747 (2026-08-14). Data as JSON: /api/errors/138ffa2ddeef1cdd. Report an issue: GitHub.

Appendix: source

Thrown at mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.java:193

        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 bf67d90747)