{"record":{"id":"f25f8c5f1e7a39d4","repo":"baomidou/mybatis-plus","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":"mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.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/baomidou/mybatis-plus/blob/bf67d907478c724120bf76292da54abf9e73c2b3/mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.java#L421-L444","documentation":"MyBatis-Plus failed to instantiate the Configuration class via reflection (configClass.getDeclaredConstructor().newInstance()). The builder reads the configuration type from the XML '<configuration>' / environment settings and requires a public no-arg constructor. Any failure in constructor lookup or invocation is wrapped into this BuilderException.","triggerScenarios":"Building a SqlSessionFactory from mybatis-plus-config.xml whose type attribute names a custom Configuration subclass that (a) lacks a public default constructor, (b) has a constructor that throws, or (c) is not on the classpath / is abstract.","commonSituations":"Custom Configuration subclass with only a parameterized constructor; constructor performs initialization that depends on resources not available at parse time; class packaged in a shaded/fat jar with broken relocation; abstract class configured by mistake.","solutions":["Add a public no-arg constructor to the custom Configuration subclass","Verify the class is concrete, public, and on the application classpath at startup","Move any failing initialization out of the constructor (lazy-init instead)","If no customization is needed, remove the type attribute and use the default Configuration","Inspect the nested cause (ex) in the stack trace to identify the real failure"],"exampleFix":"// before\npublic class MyConfiguration extends Configuration {\n    public MyConfiguration(DataSource ds) { ... } // only ctor -> instantiation fails\n}\n// after\npublic class MyConfiguration extends Configuration {\n    public MyConfiguration() { super(); } // public no-arg ctor\n    public MyConfiguration(DataSource ds) { this(); ... }\n}","handlingStrategy":"validation","validationCode":"Class<?> cfg = Class.forName(configClassName);\nint mods = cfg.getModifiers();\nif (Modifier.isAbstract(mods) || cfg.getDeclaredConstructor().newInstance() == null) {\n    throw new IllegalStateException(\"Custom Configuration must be concrete with a public no-arg constructor\");\n}","typeGuard":null,"tryCatchPattern":"catch (BuilderException e) when starting the app; fail fast and log the nested cause: log.error(\"Config init failed: {}\", e.getCause().getMessage(), e); then abort startup — do not retry.","preventionTips":["Always give custom Configuration subclasses an explicit public no-arg constructor","Cover custom Configuration construction with a unit test that calls new XmlMybatisConfiguration() style instantiation","Keep configuration classes free of environment-dependent work in constructors"],"tags":["mybatis","configuration","reflection","startup"],"backgroundTag":null,"analyzedSha":"bf67d907478c724120bf76292da54abf9e73c2b3","analyzedAt":"2026-08-14T15:17:09.543Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}