{"record":{"id":"29addce7972e3a90","repo":"mybatis/mybatis-3","slug":"error-parsing-mapper-xml-the-xml-location-is-re","errorCode":null,"errorMessage":"Error parsing Mapper XML. The XML location is '{resource}'. Cause: {cause}","messagePattern":"Error parsing Mapper XML\\. The XML location is '(.+?)'\\. Cause: (.+?)","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java","lineNumber":132,"sourceCode":"  public XNode getSqlFragment(String refid) {\n    return sqlFragments.get(refid);\n  }\n\n  private void configurationElement(XNode context) {\n    try {\n      String namespace = context.getStringAttribute(\"namespace\");\n      if (namespace == null || namespace.isEmpty()) {\n        throw new BuilderException(\"Mapper's namespace cannot be empty\");\n      }\n      builderAssistant.setCurrentNamespace(namespace);\n      cacheRefElement(context.evalNode(\"cache-ref\"));\n      cacheElement(context.evalNode(\"cache\"));\n      parameterMapElement(context.evalNodes(\"/mapper/parameterMap\"));\n      resultMapElements(context.evalNodes(\"/mapper/resultMap\"));\n      sqlElement(context.evalNodes(\"/mapper/sql\"));\n      buildStatementFromContext(context.evalNodes(\"select|insert|update|delete\"));\n    } catch (Exception e) {\n      throw new BuilderException(\"Error parsing Mapper XML. The XML location is '\" + resource + \"'. Cause: \" + e, e);\n    }\n  }\n\n  private void buildStatementFromContext(List<XNode> list) {\n    if (configuration.getDatabaseId() != null) {\n      buildStatementFromContext(list, configuration.getDatabaseId());\n    }\n    buildStatementFromContext(list, null);\n  }\n\n  private void buildStatementFromContext(List<XNode> list, String requiredDatabaseId) {\n    for (XNode context : list) {\n      final XMLStatementBuilder statementParser = new XMLStatementBuilder(configuration, builderAssistant, context,\n          requiredDatabaseId, mapperClass);\n      try {\n        statementParser.parseStatementNode();\n      } catch (IncompleteElementException e) {\n        configuration.addIncompleteStatement(statementParser);","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java#L114-L150","documentation":"Catch-all thrown by XMLMapperBuilder.configurationElement(): any exception raised while parsing the body of a mapper XML (namespace, cache-ref, cache, parameterMap, resultMap, sql fragments, statements) is re-thrown with this message including the resource path and the original cause. It is a wrapper — the real problem is always in the 'Cause:' part and the nested exception, never in this message itself.","triggerScenarios":"Any malformed mapper content: empty namespace (error 66), invalid resultMap, unsupported JDBC type, bad attribute on a statement, class-not-found for a resultType/parameterType, invalid OGNL/cache-ref reference — anything inside configurationElement() that throws during XMLMapperBuilder.parse().","commonSituations":"Every mapper-level configuration mistake surfaces here, so this is the most common mybatis startup error after XML syntax errors; frequent after upgrades where attribute names or defaults changed, or when a referenced type is missing from the classpath in a packaged jar.","solutions":["Read the 'Cause: ' suffix and the nested exception stack — fix that root cause, not this wrapper","Verify the resource path printed in the message matches the file you think you are editing (stale jars and duplicate copies on the classpath are common)","After fixing, rebuild/repackage so the deployed jar contains the corrected XML"],"exampleFix":"// before: error Cause: BuilderException: Mapper's namespace cannot be empty\n<mapper>...</mapper>\n\n// after\n<mapper namespace=\"com.acme.UserMapper\">...</mapper>","handlingStrategy":"try-catch","validationCode":"// CI: build the factory to fail fast\nnew SqlSessionFactoryBuilder().build(Resources.getResourceAsStream(\"mybatis-config.xml\"));","typeGuard":null,"tryCatchPattern":"try { sqlSessionFactory = builder.build(config); } catch (BuilderException e) { log.error(\"mapper parse failed: {} cause={}\", e.getMessage(), e.getCause()); throw e; } — always unwrap the Cause to find the real error.","preventionTips":["Never troubleshoot the wrapper message; read the nested cause","Build SqlSessionFactory in a CI smoke test","Beware stale mapper copies in jars on the classpath"],"tags":["mybatis","mapper-xml","wrapper-exception","startup"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}