baomidou/mybatis-plus · error · BuilderException

Environment declaration requires a TransactionFactory.

Error message

Environment declaration requires a TransactionFactory.

What it means

Thrown by transactionManagerElement when an <environment> declaration in mybatis-config.xml has no <transactionManager> child (the XNode passed in is null). Every environment must pair a TransactionFactory with a DataSourceFactory; a missing transaction manager makes the environment unusable, so configuration parsing fails.

Source

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

        DatabaseIdProvider databaseIdProvider = (DatabaseIdProvider) resolveClass(type).getDeclaredConstructor()
            .newInstance();
        databaseIdProvider.setProperties(properties);
        Environment environment = configuration.getEnvironment();
        if (environment != null) {
            String databaseId = databaseIdProvider.getDatabaseId(environment.getDataSource());
            configuration.setDatabaseId(databaseId);
        }
    }

    private TransactionFactory transactionManagerElement(XNode context) throws Exception {
        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()) {

View on GitHub (pinned to bf67d90747)

Solutions

1. Add <transactionManager type="JDBC"/> (or MANAGED, or a custom TransactionFactory alias) inside the <environment>.
2. Ensure element order and nesting follow the DTD: environment > transactionManager, dataSource.
3. In Spring/Spring Boot apps, prefer omitting <environments> entirely and letting Spring's DataSourceTransactionManager manage transactions.

Example fix

<!-- before -->
<environment id="dev">
  <dataSource type="POOLED">...</dataSource>
</environment>

<!-- after -->
<environment id="dev">
  <transactionManager type="JDBC"/>
  <dataSource type="POOLED">...</dataSource>
</environment>

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

Catch BuilderException 'Environment declaration requires a TransactionFactory.' at startup; add the element named by the message and rebuild — deterministic, not retryable.

When it happens

Trigger: <environment id="dev"><dataSource ...>...</dataSource></environment> with no <transactionManager type="JDBC"/> element; or an empty <transactionManager/> that XPath resolves to null.

Common situations: Hand-editing the config and deleting the transactionManager block; merging environment snippets and dropping the element; beginners copying a partial example from tutorials.

Related errors

• Environment declaration requires a DataSourceFactory.
• 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/aeee564c93304668. Report an issue: GitHub.