mybatis/mybatis-3 · error · BuilderException

Error resolving class. Cause: {cause}

Error message

Error resolving class. Cause: {cause}

What it means

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.

Source

Thrown at src/main/java/org/apache/ibatis/builder/BaseBuilder.java:104

    } catch (IllegalArgumentException e) {
      throw new BuilderException("Error resolving ParameterMode. Cause: " + e, e);
    }
  }

  protected Object createInstance(String alias) {
    Class<?> clazz = resolveClass(alias);
    try {
      return clazz == null ? null : clazz.getDeclaredConstructor().newInstance();
    } catch (Exception e) {
      throw new BuilderException("Error creating instance. Cause: " + e, e);
    }
  }

  protected <T> Class<? extends T> resolveClass(String alias) {
    try {
      return alias == null ? null : resolveAlias(alias);
    } catch (Exception e) {
      throw new BuilderException("Error resolving class. Cause: " + e, e);
    }
  }

  @Deprecated(since = "3.6.0", forRemoval = true)
  protected TypeHandler<?> resolveTypeHandler(Class<?> javaType, String typeHandlerAlias) {
    return resolveTypeHandler(javaType, null, typeHandlerAlias);
  }

  @Deprecated(since = "3.6.0", forRemoval = true)
  protected TypeHandler<?> resolveTypeHandler(Class<?> javaType, Class<? extends TypeHandler<?>> typeHandlerType) {
    return resolveTypeHandler(javaType, null, typeHandlerType);
  }

  protected TypeHandler<?> resolveTypeHandler(Type propertyType, JdbcType jdbcType, String typeHandlerAlias) {
    Class<? extends TypeHandler<?>> typeHandlerType = null;
    typeHandlerType = resolveClass(typeHandlerAlias);
    if (typeHandlerType != null && !TypeHandler.class.isAssignableFrom(typeHandlerType)) {
      throw new BuilderException("Type " + typeHandlerType.getName()

View on GitHub (pinned to 008069adb1)

Solutions

1. Fix the alias/name: register custom aliases via <typeAliases><typeAlias alias="..." type="..."/></typeAliases> or use the fully-qualified class name
2. Verify the class exists on the runtime classpath (check the packaged jar/war, not just the IDE classpath
3. Trim stray whitespace/line breaks accidentally introduced into XML attributes

Example fix

<!-- before -->
<setting name="objectFactory" value="MyFactory"/> <!-- unregistered -->
<!-- after -->
<typeAliases><typeAlias alias="MyFactory" type="com.example.MyFactory"/></typeAliases>
<setting name="objectFactory" value="MyFactory"/>

try {
  Class<?> c = Class.forName(fqcn); // pre-validate FQNs
} catch (ClassNotFoundException e) { throw new IllegalStateException("missing class " + fqcn); }
// for aliases: configuration.getTypeAliasRegistry().resolveAlias(alias) in a startup check

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error resolving JdbcType. Cause: {cause}
• Error resolving ResultSetType. Cause: {cause}
• Error creating instance. Cause: {cause}
• Type {typeHandlerType} is not a valid TypeHandler because it
• Could not resolve type alias '{}'. Cause: {}

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