What causes "Failed to create a new Configuration instance." in baomidou/mybatis-plus?

Add a public no-arg constructor to the custom Configuration subclass

baomidou/mybatis-plus · error · BuilderException

Failed to create a new Configuration instance.

Error message

Failed to create a new Configuration instance.

What it means

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.

Source

Thrown at mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.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 bf67d90747)

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

Example fix

// before
public class MyConfiguration extends Configuration {
    public MyConfiguration(DataSource ds) { ... } // only ctor -> instantiation fails
}
// after
public class MyConfiguration extends Configuration {
    public MyConfiguration() { super(); } // public no-arg ctor
    public MyConfiguration(DataSource ds) { this(); ... }
}

Defensive patterns

Strategy: validation

Validate before calling

Class<?> cfg = Class.forName(configClassName);
int mods = cfg.getModifiers();
if (Modifier.isAbstract(mods) || cfg.getDeclaredConstructor().newInstance() == null) {
    throw new IllegalStateException("Custom Configuration must be concrete with a public no-arg constructor");
}

Try / catch

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.

Prevention

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

When it happens

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

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

Related errors

AI-assisted analysis of baomidou/mybatis-plus@bf67d90747 (2026-08-14). Data as JSON: /api/errors/f25f8c5f1e7a39d4. Report an issue: GitHub.