mybatis/mybatis-3 · error · BuilderException

Failed to create a new Configuration instance.

Error message

Failed to create a new Configuration instance.

What it means

Thrown by XMLConfigBuilder.newConfig() when the Configuration implementation class (chosen via the type attribute of <configuration> in XML, Configuration.setConfigClass, or the configuration setting in mybatis-settings) cannot be instantiated reflectively. The class must have a public no-arg constructor and that constructor must not throw. The original failure (NoSuchMethodException, InvocationTargetException, etc.) is attached as the cause.

Source

Thrown at src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java:439

      }
    }
  }

  private boolean isSpecifiedEnvironment(String id) {
    if (environment == null) {
      throw new BuilderException("No environment specified.");
    }
    if (id == null) {
      throw new BuilderException("Environment requires an id attribute.");
    }
    return environment.equals(id);
  }

  private static Configuration newConfig(Class<? extends Configuration> configClass) {
    try {
      return configClass.getDeclaredConstructor().newInstance();
    } catch (Exception ex) {
      throw new BuilderException("Failed to create a new Configuration instance.", ex);
    }
  }

}

View on GitHub (pinned to 008069adb1)

Solutions

1. Add a public no-arg constructor to the custom Configuration subclass and do injected setup after construction (e.g. via an Interceptor or post-build configuration)
2. If the constructor must throw-free, move initialization that can fail into a lifecycle hook instead of the constructor
3. Verify the class is public, concrete, and on the runtime classpath; inspect the nested cause to identify which reflection step failed

Example fix

// before
public class MyConfiguration extends Configuration {
  public MyConfiguration(DataSource ds) { ... } // no no-arg ctor
}

// after
public class MyConfiguration extends Configuration {
  public MyConfiguration() { super(); }
  public void init(DataSource ds) { ... } // called after build
}

Class<? extends Configuration> c = ...;
try { c.getDeclaredConstructor(); } catch (NoSuchMethodException e) {
  throw new IllegalStateException(c + " needs a public no-arg constructor", e);
}

null

try { factory = new SqlSessionFactoryBuilder().build(in, env, props); } catch (BuilderException e) { log config-class failure with e.getCause(); abort startup; }

When it happens

Trigger: Specifying a custom Configuration subclass that (a) has no public no-arg constructor, (b) is abstract or non-public, or (c) whose no-arg constructor throws (e.g. it requires a datasource argument). e.g. <configuration type="com.acme.MyConfiguration"/> in the config properties/XML.

Common situations: Upgrading mybatis or mybatis-spring-boot and adding a custom Configuration for interceptors/DSL extensions whose constructor needs Spring beans; the custom class was written with a constructor taking arguments; class not on classpath in fat-jar/shaded deployments (cause: ClassNotFoundException).

Related errors

• Error creating instance. Cause: {cause}
• Error in result map '{resultMapId}'. Failed to find a constr
• Cannot get Configuration as factory method [" + this.configu
• Cannot get Configuration as factory class [" + this.configur
• Cannot get Configuration as factory method [" + this.configu

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