{"record":{"id":"53014df2749b75eb","repo":"mybatis/mybatis-3","slug":"error-resolving-class-cause-cause","errorCode":null,"errorMessage":"Error resolving class. Cause: {cause}","messagePattern":"Error resolving class\\. Cause: (.+?)","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/builder/BaseBuilder.java","lineNumber":104,"sourceCode":"    } catch (IllegalArgumentException e) {\n      throw new BuilderException(\"Error resolving ParameterMode. Cause: \" + e, e);\n    }\n  }\n\n  protected Object createInstance(String alias) {\n    Class<?> clazz = resolveClass(alias);\n    try {\n      return clazz == null ? null : clazz.getDeclaredConstructor().newInstance();\n    } catch (Exception e) {\n      throw new BuilderException(\"Error creating instance. Cause: \" + e, e);\n    }\n  }\n\n  protected <T> Class<? extends T> resolveClass(String alias) {\n    try {\n      return alias == null ? null : resolveAlias(alias);\n    } catch (Exception e) {\n      throw new BuilderException(\"Error resolving class. Cause: \" + e, e);\n    }\n  }\n\n  @Deprecated(since = \"3.6.0\", forRemoval = true)\n  protected TypeHandler<?> resolveTypeHandler(Class<?> javaType, String typeHandlerAlias) {\n    return resolveTypeHandler(javaType, null, typeHandlerAlias);\n  }\n\n  @Deprecated(since = \"3.6.0\", forRemoval = true)\n  protected TypeHandler<?> resolveTypeHandler(Class<?> javaType, Class<? extends TypeHandler<?>> typeHandlerType) {\n    return resolveTypeHandler(javaType, null, typeHandlerType);\n  }\n\n  protected TypeHandler<?> resolveTypeHandler(Type propertyType, JdbcType jdbcType, String typeHandlerAlias) {\n    Class<? extends TypeHandler<?>> typeHandlerType = null;\n    typeHandlerType = resolveClass(typeHandlerAlias);\n    if (typeHandlerType != null && !TypeHandler.class.isAssignableFrom(typeHandlerType)) {\n      throw new BuilderException(\"Type \" + typeHandlerType.getName()","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/builder/BaseBuilder.java#L86-L122","documentation":"BaseBuilder.resolveClass() turns an alias or fully-qualified class name from configuration into a Class object via the TypeAliasRegistry. Any failure - unknown alias, ClassNotFoundException for an FQN, or a string with stray whitespace - is wrapped into this BuilderException during parsing.","triggerScenarios":"typeHandler=\"MyHandler \" (trailing space); alias=\"mytype\" never registered via typeAliases; javaType=\"int2\" typo; an FQN referencing a class not on the classpath (missing dependency jar); copying config from another project without its custom alias registrations.","commonSituations":"Splitting config files and losing the <typeAliases> block; typo'd aliases; shaded/renamed packages breaking FQNs after refactoring; optional dependencies not included in the deployment artifact.","solutions":["Fix the alias/name: register custom aliases via <typeAliases><typeAlias alias=\"...\" type=\"...\"/></typeAliases> or use the fully-qualified class name","Verify the class exists on the runtime classpath (check the packaged jar/war, not just the IDE classpath","Trim stray whitespace/line breaks accidentally introduced into XML attributes"],"exampleFix":"<!-- before -->\n<setting name=\"objectFactory\" value=\"MyFactory\"/> <!-- unregistered -->\n<!-- after -->\n<typeAliases><typeAlias alias=\"MyFactory\" type=\"com.example.MyFactory\"/></typeAliases>\n<setting name=\"objectFactory\" value=\"MyFactory\"/>","handlingStrategy":"validation","validationCode":"try {\n  Class<?> c = Class.forName(fqcn); // pre-validate FQNs\n} catch (ClassNotFoundException e) { throw new IllegalStateException(\"missing class \" + fqcn); }\n// for aliases: configuration.getTypeAliasRegistry().resolveAlias(alias) in a startup check","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Register custom aliases once in a shared <typeAliases> block","Prefer fully-qualified names in config to avoid alias drift","Parse full configuration in a startup test so class/alias errors surface at deploy time"],"tags":["mybatis","builder","class-resolution","type-alias","configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}