{"record":{"id":"90bdbdbae26ad148","repo":"mybatis/mybatis-3","slug":"failed-to-create-a-new-configuration-instance","errorCode":null,"errorMessage":"Failed to create a new Configuration instance.","messagePattern":"Failed to create a new Configuration instance\\.","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java","lineNumber":439,"sourceCode":"      }\n    }\n  }\n\n  private boolean isSpecifiedEnvironment(String id) {\n    if (environment == null) {\n      throw new BuilderException(\"No environment specified.\");\n    }\n    if (id == null) {\n      throw new BuilderException(\"Environment requires an id attribute.\");\n    }\n    return environment.equals(id);\n  }\n\n  private static Configuration newConfig(Class<? extends Configuration> configClass) {\n    try {\n      return configClass.getDeclaredConstructor().newInstance();\n    } catch (Exception ex) {\n      throw new BuilderException(\"Failed to create a new Configuration instance.\", ex);\n    }\n  }\n\n}\n","sourceCodeStart":421,"sourceCodeEnd":444,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java#L421-L444","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["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)","If the constructor must throw-free, move initialization that can fail into a lifecycle hook instead of the constructor","Verify the class is public, concrete, and on the runtime classpath; inspect the nested cause to identify which reflection step failed"],"exampleFix":"// before\npublic class MyConfiguration extends Configuration {\n  public MyConfiguration(DataSource ds) { ... } // no no-arg ctor\n}\n\n// after\npublic class MyConfiguration extends Configuration {\n  public MyConfiguration() { super(); }\n  public void init(DataSource ds) { ... } // called after build\n}","handlingStrategy":"try-catch","validationCode":"Class<? extends Configuration> c = ...;\ntry { c.getDeclaredConstructor(); } catch (NoSuchMethodException e) {\n  throw new IllegalStateException(c + \" needs a public no-arg constructor\", e);\n}","typeGuard":"null","tryCatchPattern":"try { factory = new SqlSessionFactoryBuilder().build(in, env, props); } catch (BuilderException e) { log config-class failure with e.getCause(); abort startup; }","preventionTips":["Give custom Configuration subclasses an explicit public no-arg constructor","Unit-test instantiation of the custom config class in CI"],"tags":["mybatis","reflection","custom-configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}