baomidou/mybatis-plus · error · BuilderException

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

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.

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)

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

• %s already contains value for %s
• %s does not contain value for %s
• %s is ambiguous in %s (try using the full name including the
• Should be specified either value() or name() attribute in th
• Cannot use both value() and name() attribute in the @CacheNa

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