baomidou/mybatis-plus · error · BuilderException

A mapper element may only specify a url, resource or class,

Error message

A mapper element may only specify a url, resource or class, but not more than one.

What it means

Thrown by mappersElement when a <mapper> element in mybatis-config.xml specifies none or several of the attributes url, resource, and class. The parser handles the three single-attribute combinations explicitly (resource only, url only, class only); everything else — including two or three attributes set, or none — falls into the final else branch and throws.

Source

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

                if (resource != null && url == null && mapperClass == null) {
                    ErrorContext.instance().resource(resource);
                    try (InputStream inputStream = Resources.getResourceAsStream(resource)) {
                        XMLMapperBuilder mapperParser = new XMLMapperBuilder(inputStream, configuration, resource,
                            configuration.getSqlFragments());
                        mapperParser.parse();
                    }
                } else if (resource == null && url != null && mapperClass == null) {
                    ErrorContext.instance().resource(url);
                    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 {

View on GitHub (pinned to bf67d90747)

Solutions

Split into separate <mapper> elements, each with exactly one attribute: <mapper resource="..."/>, <mapper url="..."/>, or <mapper class="..."/>.
For bulk registration prefer <package name="com.example.mapper"/> to scan a whole package.
Remove empty <mapper/> elements left by templating.

Example fix

<!-- before -->
<mappers>
  <mapper resource="mapper/UserMapper.xml" class="com.example.mapper.UserMapper"/>
</mappers>

<!-- after -->
<mappers>
  <mapper resource="mapper/UserMapper.xml"/>
  <mapper class="com.example.mapper.OtherMapper"/>
</mappers>

Defensive patterns

Strategy: validation

Validate before calling

// each <mapper> must carry exactly one of resource/url/class
org.w3c.dom.NodeList ms = doc.getElementsByTagName("mapper");
for (int i = 0; i < ms.getLength(); i++) {
    org.w3c.dom.Element el = (org.w3c.dom.Element) ms.item(i);
    int attrs = Stream.of("resource", "url", "class").map(a -> el.hasAttribute(a) ? 1 : 0)
        .mapToInt(Integer::intValue).sum();
    if (attrs != 1) throw new IllegalStateException("<mapper> must have exactly one of resource/url/class: " + el);
}

Try / catch

Catch BuilderException 'A mapper element may only specify a url, resource or class'; split the offending element into one-attribute elements.

Prevention

One attribute per <mapper> element by convention.
Use <package> for bulk interface registration.

When it happens

Trigger: <mapper resource="mappers/User.xml" class="com.example.UserMapper"/> (two attributes), or an empty <mapper/> with no attributes.

Common situations: Adding a class attribute while a resource attribute already exists; templating mistakes producing empty <mapper/> elements; misunderstanding that one element registers exactly one mapper.

Related errors

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