{"record":{"id":"138ffa2ddeef1cdd","repo":"baomidou/mybatis-plus","slug":"error-registering-typealias-for-s-cause-s","errorCode":null,"errorMessage":"Error registering typeAlias for '%s'. Cause: %s","messagePattern":"Error registering typeAlias for '(.+?)'\\. Cause: (.+?)","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.java","lineNumber":193,"sourceCode":"        if (context == null) {\n            return;\n        }\n        for (XNode child : context.getChildren()) {\n            if (\"package\".equals(child.getName())) {\n                String typeAliasPackage = child.getStringAttribute(\"name\");\n                configuration.getTypeAliasRegistry().registerAliases(typeAliasPackage);\n            } else {\n                String alias = child.getStringAttribute(\"alias\");\n                String type = child.getStringAttribute(\"type\");\n                try {\n                    Class<?> clazz = Resources.classForName(type);\n                    if (alias == null) {\n                        typeAliasRegistry.registerAlias(clazz);\n                    } else {\n                        typeAliasRegistry.registerAlias(alias, clazz);\n                    }\n                } catch (ClassNotFoundException e) {\n                    throw new BuilderException(\"Error registering typeAlias for '\" + alias + \"'. Cause: \" + e, e);\n                }\n            }\n        }\n    }\n\n    private void pluginsElement(XNode context) throws Exception {\n        if (context != null) {\n            for (XNode child : context.getChildren()) {\n                String interceptor = child.getStringAttribute(\"interceptor\");\n                Properties properties = child.getChildrenAsProperties();\n                Interceptor interceptorInstance = (Interceptor) resolveClass(interceptor).getDeclaredConstructor()\n                    .newInstance();\n                interceptorInstance.setProperties(properties);\n                configuration.addInterceptor(interceptorInstance);\n            }\n        }\n    }\n","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/baomidou/mybatis-plus/blob/bf67d907478c724120bf76292da54abf9e73c2b3/mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.java#L175-L211","documentation":"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.","triggerScenarios":"<typeAlias alias=\"user\" type=\"com.exmaple.User\"/> where the class does not exist on the classpath (typo, wrong package, missing dependency).","commonSituations":"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.","solutions":["Fix the type attribute to the correct fully-qualified class name (copy from the actual class's package declaration).","If the class lives in another module/jar, add that artifact as a runtime dependency.","Prefer <package name=\"com.example.entity\"/> bulk registration to avoid hand-written FQCNs, letting MyBatis scan the package."],"exampleFix":"<!-- before -->\n<typeAliases>\n  <typeAlias alias=\"user\" type=\"com.exmaple.entity.User\"/>\n</typeAliases>\n\n<!-- after -->\n<typeAliases>\n  <typeAlias alias=\"user\" type=\"com.example.entity.User\"/>\n</typeAliases>","handlingStrategy":"validation","validationCode":"// verify typeAlias classes are loadable before parsing\nfor (String fqcn : List.of(\"com.example.entity.User\")) {\n    Class.forName(fqcn); // throws early with the exact class name\n}","typeGuard":null,"tryCatchPattern":"Catch BuilderException starting 'Error registering typeAlias for'; the alias and CNFE cause name the offending entry — fix the FQCN in XML.","preventionTips":["Use <package name=\"...\"/> scanning instead of per-class typeAlias entries.","Run a classpath assertions test that all XML-referenced classes resolve."],"tags":["mybatis","mybatis-plus","type-alias","class-not-found","configuration"],"backgroundTag":null,"analyzedSha":"bf67d907478c724120bf76292da54abf9e73c2b3","analyzedAt":"2026-08-14T15:17:09.543Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}