What causes "Error parsing SQL Mapper Configuration. Cause: %s" in baomidou/mybatis-plus?

Read the full message and stack trace to the root cause (getCause()); fix that underlying error, not this wrapper.

baomidou/mybatis-plus · error · BuilderException

Error parsing SQL Mapper Configuration. Cause: %s

Error message

Error parsing SQL Mapper Configuration. Cause: %s

What it means

Generic wrapper thrown by parseConfiguration for any exception raised while walking the mybatis-config.xml tree (properties, settings, typeAliases, plugins, environments, typeHandlers, mappers sections). It is a facade: the specific failure is in the message ('Cause: ...') and the suppressed cause, so the real error — bad class name, malformed XML section, invalid setting — must be extracted from the cause chain.

Source

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

        try {
            // issue #117 read properties first
            propertiesElement(root.evalNode("properties"));
            Properties settings = settingsAsProperties(root.evalNode("settings"));
            loadCustomVfsImpl(settings);
            loadCustomLogImpl(settings);
            typeAliasesElement(root.evalNode("typeAliases"));
            pluginsElement(root.evalNode("plugins"));
            objectFactoryElement(root.evalNode("objectFactory"));
            objectWrapperFactoryElement(root.evalNode("objectWrapperFactory"));
            reflectorFactoryElement(root.evalNode("reflectorFactory"));
            settingsElement(settings);
            // read it after objectFactory and objectWrapperFactory issue #631
            environmentsElement(root.evalNode("environments"));
            databaseIdProviderElement(root.evalNode("databaseIdProvider"));
            typeHandlersElement(root.evalNode("typeHandlers"));
            mappersElement(root.evalNode("mappers"));
        } catch (Exception e) {
            throw new BuilderException("Error parsing SQL Mapper Configuration. Cause: " + e, e);
        }
    }

    private Properties settingsAsProperties(XNode context) {
        if (context == null) {
            return new Properties();
        }
        Properties props = context.getChildrenAsProperties();
        // Check that all settings are known to the configuration class
        MetaClass metaConfig = MetaClass.forClass(Configuration.class, localReflectorFactory);
        for (Object key : props.keySet()) {
            if (!metaConfig.hasSetter(String.valueOf(key))) {
                throw new BuilderException(
                    "The setting " + key + " is not known.  Make sure you spelled it correctly (case sensitive).");
            }
        }
        return props;
    }

View on GitHub (pinned to bf67d90747)

Solutions

Read the full message and stack trace to the root cause (getCause()); fix that underlying error, not this wrapper.
Validate the mybatis-config.xml element order and required children per the DTD (properties, settings, typeAliases, plugins, environments, mappers).
Check that every class referenced in the config exists at the stated package and has a public no-arg constructor.
Confirm referenced property files/resources resolve on the classpath at runtime.

Example fix

<!-- before: class moved during refactor -->
<plugins>
  <plugin interceptor="com.example.oldpkg.MyPlugin"/>
</plugins>

<!-- after -->
<plugins>
  <plugin interceptor="com.example.plugins.MyPlugin"/>
</plugins>

Defensive patterns

Strategy: try-catch

Validate before calling

// validate XML against the MyBatis DTD before parsing
javax.xml.XMLConstants fac = null; // placeholder
SchemaFactory sf = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
// simplest practical validation: parse with DTD enabled in XMLConfigBuilder (it does by default)
// and dry-run build at startup in a test:
new SqlSessionFactoryBuilder().build(Resources.getResourceAsReader("mybatis-config.xml"));

Try / catch

catch (org.apache.ibatis.builder.BuilderException e) { log.error("Config parse failed: {}", e.getMessage(), e.getCause()); fail startup; } — always log the cause chain; the actionable error is e.getCause().

Prevention

Build the SqlSessionFactory in a unit/@SpringBootTest test so XML errors surface at build time.
Keep class references in XML synced with refactoring tools or generate them.
Run config through an XML lint with the MyBatis DTD.

When it happens

Trigger: Any parse-time failure inside mybatis-config.xml: a <typeAlias> pointing to a missing class, an <environment> without a <transactionManager>, an interceptor class lacking a no-arg constructor, an unresolvable <properties resource=...>, or any child section throwing.

Common situations: Typos in fully-qualified class names inside the XML config; refactoring moving plugin classes without updating the config; environment-specific configs referencing resources absent from the classpath.

Related errors

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