baomidou/mybatis-plus · error · BuilderException

Environment declaration requires a DataSourceFactory.

Error message

Environment declaration requires a DataSourceFactory.

What it means

Thrown by dataSourceElement when an <environment> declaration has no <dataSource> child. Symmetric with the transactionManager check: an environment needs both a TransactionFactory and a DataSourceFactory, and a missing dataSource leaves MyBatis with no way to obtain connections, so parsing aborts.

Source

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

        if (context != null) {
            String type = context.getStringAttribute("type");
            Properties props = context.getChildrenAsProperties();
            TransactionFactory factory = (TransactionFactory) resolveClass(type).getDeclaredConstructor().newInstance();
            factory.setProperties(props);
            return factory;
        }
        throw new BuilderException("Environment declaration requires a TransactionFactory.");
    }

    private DataSourceFactory dataSourceElement(XNode context) throws Exception {
        if (context != null) {
            String type = context.getStringAttribute("type");
            Properties props = context.getChildrenAsProperties();
            DataSourceFactory factory = (DataSourceFactory) resolveClass(type).getDeclaredConstructor().newInstance();
            factory.setProperties(props);
            return factory;
        }
        throw new BuilderException("Environment declaration requires a DataSourceFactory.");
    }

    private void typeHandlersElement(XNode context) {
        if (context == null) {
            return;
        }
        for (XNode child : context.getChildren()) {
            if ("package".equals(child.getName())) {
                String typeHandlerPackage = child.getStringAttribute("name");
                typeHandlerRegistry.register(typeHandlerPackage);
            } else {
                String javaTypeName = child.getStringAttribute("javaType");
                String jdbcTypeName = child.getStringAttribute("jdbcType");
                String handlerTypeName = child.getStringAttribute("handler");
                Class<?> javaTypeClass = resolveClass(javaTypeName);
                JdbcType jdbcType = resolveJdbcType(jdbcTypeName);
                Class<?> typeHandlerClass = resolveClass(handlerTypeName);
                if (javaTypeClass != null) {

View on GitHub (pinned to bf67d90747)

Solutions

1. Add a <dataSource type="POOLED"> block with <property> entries for driver, url, username, password.
2. If Spring manages the DataSource, remove the whole <environments> section and build SqlSessionFactory from the Spring-managed DataSource.
3. Validate the XML against the MyBatis DTD to catch missing required children early.

Example fix

<!-- before -->
<environment id="dev">
  <transactionManager type="JDBC"/>
</environment>

<!-- after -->
<environment id="dev">
  <transactionManager type="JDBC"/>
  <dataSource type="POOLED">
    <property name="driver" value="org.h2.Driver"/>
    <property name="url" value="jdbc:h2:mem:test"/>
  </dataSource>
</environment>

// ensure each <environment> has a <dataSource>
for (int i = 0; i < envs.getLength(); i++) {
    org.w3c.dom.Element env = (org.w3c.dom.Element) envs.item(i);
    if (env.getElementsByTagName("dataSource").getLength() == 0)
        throw new IllegalStateException("environment " + env.getAttribute("id") + " lacks dataSource");
}

Catch BuilderException 'Environment declaration requires a DataSourceFactory.'; add the <dataSource type="POOLED"> block or remove <environments> in favor of Spring's DataSource.

When it happens

Trigger: <environment id="dev"><transactionManager type="JDBC"/></environment> with the <dataSource> element missing or empty.

Common situations: Truncation during config templating; moving datasource definition to Spring but leaving a residual <environments> block without <dataSource>; XML merge tools dropping elements.

Related errors

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

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