mybatis/mybatis-3 · error · BuilderException

Error creating document instance. Cause: {}

Error message

Error creating document instance.  Cause: {}

What it means

XPathParser.createDocument() wraps any exception thrown while building and parsing the DOM document (DocumentBuilder.parse) into a BuilderException. It means the XML itself could not be turned into a Document at all.

Source

Thrown at src/main/java/org/apache/ibatis/parsing/XPathParser.java:262

      builder.setErrorHandler(new ErrorHandler() {
        @Override
        public void error(SAXParseException exception) throws SAXException {
          throw exception;
        }

        @Override
        public void fatalError(SAXParseException exception) throws SAXException {
          throw exception;
        }

        @Override
        public void warning(SAXParseException exception) throws SAXException {
          // NOP
        }
      });
      return builder.parse(inputSource);
    } catch (Exception e) {
      throw new BuilderException("Error creating document instance.  Cause: " + e, e);
    }
  }

  private void commonConstructor(boolean validation, Properties variables, EntityResolver entityResolver) {
    this.validation = validation;
    this.entityResolver = entityResolver;
    this.variables = variables;
    XPathFactory factory = XPathFactory.newInstance();
    this.xpath = factory.newXPath();
  }

}

View on GitHub (pinned to 008069adb1)

Solutions

1. Open the file named in the cause and validate well-formedness with any XML validator.
2. Fix the reported line/column from the SAXParseException in the cause chain.
3. Verify encoding declarations match the actual file encoding and that the resource path points at the intended file.

Example fix

<!-- before: unclosed tag -->
<select id="find">SELECT 1
<!-- after -->
<select id="find">SELECT 1</select>

// pre-validate before handing to MyBatis
DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
f.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
f.newDocumentBuilder().parse(new InputSource(new StringReader(mapperXml))); // throws early with line/column

When it happens

Trigger: Feeding XMLMapperBuilder/XMLConfigBuilder a resource that is not well-formed XML: unbalanced tags, bad encoding declaration, illegal characters, or a stream the parser rejects.

Common situations: Mapper XML with a typo (unclosed tag, stray '<'), BOM/encoding mismatch, file truncated during build, HTML error page returned where XML was expected, classpath resource resolution returning the wrong bytes.

Related errors

• Error evaluating XPath. Cause: {}
• Line missing end-of-line terminator ({}) => {}
• Unknown element <" + nodeName + "> in SQL statement.
• Too many default (otherwise) elements in choose statement.
• Unknown execution method for: {name}

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/87a6bb542728156f. Report an issue: GitHub.