mybatis/mybatis-3 · error · BuilderException

Error evaluating XPath. Cause: {}

Error message

Error evaluating XPath.  Cause: {}

What it means

XPathParser.evaluate() wraps any exception thrown by javax.xml.xpath.XPath.evaluate() into a BuilderException. This is MyBatis-internal XPath evaluation over the parsed mapper/config DOM, so a failure means the XPath expression could not be applied to the document.

Source

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

  }

  public XNode evalNode(String expression) {
    return evalNode(document, expression);
  }

  public XNode evalNode(Object root, String expression) {
    Node node = (Node) evaluate(expression, root, XPathConstants.NODE);
    if (node == null) {
      return null;
    }
    return new XNode(this, node, variables);
  }

  private Object evaluate(String expression, Object root, QName returnType) {
    try {
      return xpath.evaluate(expression, root, returnType);
    } catch (Exception e) {
      throw new BuilderException("Error evaluating XPath.  Cause: " + e, e);
    }
  }

  private Document createDocument(InputSource inputSource) {
    // important: this must only be called AFTER common constructor
    try {
      DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
      factory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
      factory.setValidating(validation);

      factory.setNamespaceAware(false);
      factory.setIgnoringComments(true);
      factory.setIgnoringElementContentWhitespace(false);
      factory.setCoalescing(false);
      factory.setExpandEntityReferences(false);

      DocumentBuilder builder = factory.newDocumentBuilder();
      builder.setEntityResolver(entityResolver);

View on GitHub (pinned to 008069adb1)

Solutions

1. Validate the mapper/configuration XML against the MyBatis DTD/XSD and fix structural issues.
2. If using XPathParser directly, test the XPath expression in isolation (e.g. with a plain XPath engine) before passing it.
3. Check the cause chain in the BuilderException — the wrapped exception states the exact XPath failure.

try {
  XNode node = parser.evalNode("/configuration/environments");
} catch (BuilderException e) {
  // log the cause chain; the wrapped XPathException pinpoints the bad expression
}

When it happens

Trigger: Malformed or exotic XML that leads internal evalNode/eval calls astray, or a caller using XPathParser's public eval* methods with an invalid XPath expression (syntax error or unsupported construct).

Common situations: Custom tooling built on XPathParser passing hand-crafted XPath strings; corrupted or non-standard mapper XML (wrong DOCTYPE, unexpected element names) that breaks internal lookups.

Related errors

• Error creating document instance. 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/6a793fd2e8088690. Report an issue: GitHub.