mybatis/mybatis-3 · error · BuilderException

Error creating instance. Cause: {cause}

Error message

Error creating instance. Cause: {cause}

What it means

BaseBuilder.createInstance(alias) resolves an alias/short name to a Class and then calls its declared no-arg constructor via reflection. Any constructor failure - missing no-arg constructor, non-public constructor, or constructor that throws - is wrapped into this BuilderException. It instantiates pluggable components named in configuration: objectFactory, objectWrapperFactory, reflectorFactory, typeHandler, javaType wrappers, cache implementations, etc.

Source

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

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

  protected ParameterMode resolveParameterMode(String alias) {
    try {
      return alias == null ? null : ParameterMode.valueOf(alias);
    } 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) {

View on GitHub (pinned to 008069adb1)

Solutions

1. Read the chained 'Cause:' to identify the constructor failure, then add a public no-arg constructor to the class
2. If the constructor throws, fix the underlying initialization error (missing resource, null config, etc.)
3. Ensure the class and its constructor are public and accessible to the MyBatis classloader

Example fix

// before
public class MyHandler extends BaseTypeHandler<String> {
  public MyHandler(DataSource ds) { ... }
}
<!-- after -->
public class MyHandler extends BaseTypeHandler<String> {
  public MyHandler() { ... }
  public MyHandler(DataSource ds) { this(); ... }
}

Class<?> c = Class.forName("com.example.MyHandler");
if (!Modifier.isPublic(c.getModifiers())) throw new IllegalStateException("handler must be public");
c.getDeclaredConstructor(); // throws NoSuchMethodException if no no-arg constructor exists

catch (BuilderException e) { log.error("instantiation failed: {}", e.getCause()); throw e; }

When it happens

Trigger: typeHandler="com.example.MyHandler" where MyHandler has no public no-arg constructor; an objectFactory class whose constructor throws; defaultCache or eviction/class implementations without accessible constructors; class found but in a module/OJPMS context where the constructor is not exported.

Common situations: Custom TypeHandler or Cache written with only a parameterized constructor; constructor performing initialization that fails (e.g. reads a resource that is absent); Java 16+ strong encapsulation blocking reflective access.

Related errors

• Error resolving JdbcType. Cause: {cause}
• Error resolving ResultSetType. Cause: {cause}
• Error resolving class. Cause: {cause}
• Type {typeHandlerType} is not a valid TypeHandler because it
• Cannot get Configuration as factory method [" + this.configu

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