{"record":{"id":"87a6bb542728156f","repo":"mybatis/mybatis-3","slug":"error-creating-document-instance-cause","errorCode":null,"errorMessage":"Error creating document instance.  Cause: {}","messagePattern":"Error creating document instance\\.  Cause: (.+?)","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/parsing/XPathParser.java","lineNumber":262,"sourceCode":"      builder.setErrorHandler(new ErrorHandler() {\n        @Override\n        public void error(SAXParseException exception) throws SAXException {\n          throw exception;\n        }\n\n        @Override\n        public void fatalError(SAXParseException exception) throws SAXException {\n          throw exception;\n        }\n\n        @Override\n        public void warning(SAXParseException exception) throws SAXException {\n          // NOP\n        }\n      });\n      return builder.parse(inputSource);\n    } catch (Exception e) {\n      throw new BuilderException(\"Error creating document instance.  Cause: \" + e, e);\n    }\n  }\n\n  private void commonConstructor(boolean validation, Properties variables, EntityResolver entityResolver) {\n    this.validation = validation;\n    this.entityResolver = entityResolver;\n    this.variables = variables;\n    XPathFactory factory = XPathFactory.newInstance();\n    this.xpath = factory.newXPath();\n  }\n\n}\n","sourceCodeStart":244,"sourceCodeEnd":275,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/parsing/XPathParser.java#L244-L275","documentation":"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.","triggerScenarios":"Feeding XMLMapperBuilder/XMLConfigBuilder a resource that is not well-formed XML: unbalanced tags, bad encoding declaration, illegal characters, or a stream the parser rejects.","commonSituations":"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.","solutions":["Open the file named in the cause and validate well-formedness with any XML validator.","Fix the reported line/column from the SAXParseException in the cause chain.","Verify encoding declarations match the actual file encoding and that the resource path points at the intended file."],"exampleFix":"<!-- before: unclosed tag -->\n<select id=\"find\">SELECT 1\n<!-- after -->\n<select id=\"find\">SELECT 1</select>","handlingStrategy":"validation","validationCode":"// pre-validate before handing to MyBatis\nDocumentBuilderFactory f = DocumentBuilderFactory.newInstance();\nf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);\nf.newDocumentBuilder().parse(new InputSource(new StringReader(mapperXml))); // throws early with line/column","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run mapper XML through an XML well-formedness check in CI.","Serve mapper resources from versioned classpath locations to avoid truncated or wrong files."],"tags":["mybatis","xml","parsing","well-formedness"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}