baomidou/mybatis-plus · error · BuilderException

Error parsing Mapper XML. The XML location is '%s'. Cause: %

Error message

Error parsing Mapper XML. The XML location is '%s'. Cause: %s

What it means

Generic wrapper thrown by MybatisXMLMapperBuilder.configurationElement when any exception occurs while parsing the body of a mapper XML file (cache-ref, cache, parameterMap, resultMap, sql fragments, or select/insert/update/delete statements). The original exception is preserved as the cause and the offending resource path is included in the message.

Source

Thrown at mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLMapperBuilder.java:129

    public XNode getSqlFragment(String refid) {
        return sqlFragments.get(refid);
    }

    private void configurationElement(XNode context) {
        try {
            String namespace = context.getStringAttribute("namespace");
            if (namespace == null || namespace.isEmpty()) {
                throw new BuilderException("Mapper's namespace cannot be empty");
            }
            builderAssistant.setCurrentNamespace(namespace);
            cacheRefElement(context.evalNode("cache-ref"));
            cacheElement(context.evalNode("cache"));
            parameterMapElement(context.evalNodes("/mapper/parameterMap"));
            resultMapElements(context.evalNodes("/mapper/resultMap"));
            sqlElement(context.evalNodes("/mapper/sql"));
            buildStatementFromContext(context.evalNodes("select|insert|update|delete"));
        } catch (Exception e) {
            throw new BuilderException("Error parsing Mapper XML. The XML location is '" + resource + "'. Cause: " + e, e);
        }
    }

    private void buildStatementFromContext(List<XNode> list) {
        if (configuration.getDatabaseId() != null) {
            buildStatementFromContext(list, configuration.getDatabaseId());
        }
        buildStatementFromContext(list, null);
    }

    private void buildStatementFromContext(List<XNode> list, String requiredDatabaseId) {
        for (XNode context : list) {
            final XMLStatementBuilder statementParser = new XMLStatementBuilder(configuration, builderAssistant, context,
                requiredDatabaseId);
            try {
                statementParser.parseStatementNode();
            } catch (IncompleteElementException e) {
                configuration.addIncompleteStatement(statementParser);

View on GitHub (pinned to bf67d90747)

Solutions

1. Read the 'Cause:' portion of the message and the nested cause exception to identify the real error
2. Open the file at the reported XML location and fix the specific element identified by the cause
3. Validate the XML against the mybatis mapper DTD/XSD in the IDE
4. If the cause is a ClassNotFoundException, fix the resultType/parameterType FQCN

Example fix

<!-- before: com.exmaple typo -->
<resultMap id="userMap" type="com.exmaple.entity.User">
<!-- after -->
<resultMap id="userMap" type="com.example.entity.User">

try { sqlSessionFactory.build(...); } catch (BuilderException e) { String resource = extractBetween(e.getMessage(), "location is '", "'. Cause"); log.error("Mapper XML {} failed: {}", resource, e.getCause().getMessage()); throw e; }

When it happens

Trigger: Any malformed resultMap, bad resultType/parameterType class name, duplicate statement id, invalid cache-ref, SQL script element errors, or missing namespace inside a mapper XML matched by mapper-locations.

Common situations: Typo in a fully-qualified class name in resultType; XML that violates the mapper DTD; duplicate statement ids across included sql fragments; refactoring renamed an entity but XML still references the old name.

Related errors

• Mapper's namespace cannot be empty
• Unknown element <%s> in SQL statement.
• %s already contains value for %s
• %s does not contain value for %s
• Ambiguous collection type for property '%s'. You must specif

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