baomidou/mybatis-plus · error · BuilderException

No environment specified.

Error message

No environment specified.

What it means

Thrown by isSpecifiedEnvironment when the builder was constructed without an environment id and encounters an <environments> section trying to match one. The environment field is set only when the caller (e.g. SqlSessionFactoryBuilder.build(config, environmentId)) supplies one; with it null, MyBatis cannot select which <environment> to activate and fails.

Source

Thrown at mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.java:427

                    try (InputStream inputStream = Resources.getUrlAsStream(url)) {
                        XMLMapperBuilder mapperParser = new XMLMapperBuilder(inputStream, configuration, url,
                            configuration.getSqlFragments());
                        mapperParser.parse();
                    }
                } else if (resource == null && url == null && mapperClass != null) {
                    Class<?> mapperInterface = Resources.classForName(mapperClass);
                    configuration.addMapper(mapperInterface);
                } else {
                    throw new BuilderException(
                        "A mapper element may only specify a url, resource or class, but not more than one.");
                }
            }
        }
    }

    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

1. Pass an explicit environment id: new SqlSessionFactoryBuilder().build(reader, "development").
2. Or mark one environment as default via <environments default="development"> so parsing can pick it automatically.
3. In Spring Boot, delete the <environments> block entirely and inject the Spring-managed DataSource.

Example fix

// before
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader);

// after
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, "development");

// decide environment id up front and pass it explicitly
String envId = System.getProperty("app.env", "development");
// ensure it exists in the XML before building
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, envId);

Catch BuilderException 'No environment specified.' from build(); re-run with an explicit environment id argument or set the default attribute in <environments>.

When it happens

Trigger: Building with new SqlSessionFactoryBuilder().build(reader) — no environment argument — while the mybatis-config.xml contains multiple <environment> definitions so no default can be inferred, or explicitly calling build(reader, null).

Common situations: Adding a second <environment> to a config previously parsed with a single default environment; wrapping the builder in custom code that drops the environment parameter; tests reusing a config file with several environments but no environment id passed.

Related errors

• Each XMLConfigBuilder can only be used once.
• Environment declaration requires a TransactionFactory.
• Environment declaration requires a DataSourceFactory.
• Environment requires an id attribute.
• Error parsing SQL Mapper Configuration. Cause: %s

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