{"record":{"id":"2adeb0d5965b2c5a","repo":"baomidou/mybatis-plus","slug":"mapper-s-namespace-cannot-be-empty","errorCode":null,"errorMessage":"Mapper's namespace cannot be empty","messagePattern":"Mapper's namespace cannot be empty","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLMapperBuilder.java","lineNumber":119,"sourceCode":"        if (!configuration.isResourceLoaded(resource)) {\n            configurationElement(parser.evalNode(\"/mapper\"));\n            configuration.addLoadedResource(resource);\n            bindMapperForNamespace();\n        }\n        configuration.parsePendingResultMaps(false);\n        configuration.parsePendingCacheRefs(false);\n        configuration.parsePendingStatements(false);\n    }\n\n    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);","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/baomidou/mybatis-plus/blob/bf67d907478c724120bf76292da54abf9e73c2b3/mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLMapperBuilder.java#L101-L137","documentation":"While parsing a mapper XML file, the required 'namespace' attribute of the root <mapper> element was missing or empty. The namespace binds the XML statements to a mapper interface (or class) and is mandatory; without it the builder cannot register statements or resolve full statement ids.","triggerScenarios":"A mapper XML file whose root element is '<mapper>' with no namespace attribute, namespace=\"\", or namespace containing only whitespace; the file is picked up via mapper-locations scanning (e.g. classpath*:mapper/*.xml).","commonSituations":"Hand-written or generated XML files with the namespace accidentally deleted; template placeholders (e.g. ${namespace}) left unfilled; a stray non-mapper XML file matched by an overly broad mapper-locations glob.","solutions":["Add the mapper interface FQCN as the namespace: <mapper namespace=\"com.example.mapper.UserMapper\">","Check the exact resource named in the error's wrapping message ('The XML location is ...') to find the offending file","Tighten mapper-locations patterns so non-mapper XML files are not scanned","If using code generation, fix the template so namespace is always emitted"],"exampleFix":"<!-- before -->\n<mapper>\n  <select id=\"findById\" resultType=\"User\">...</select>\n</mapper>\n<!-- after -->\n<mapper namespace=\"com.example.mapper.UserMapper\">\n  <select id=\"findById\" resultType=\"User\">...</select>\n</mapper>","handlingStrategy":"validation","validationCode":"// CI check: every mapper XML must declare a non-empty namespace\nDocumentBuilderFactory f = DocumentBuilderFactory.newInstance();\nDocument d = f.newDocumentBuilder().parse(xmlFile);\nElement root = d.getDocumentElement();\nif (!\"mapper\".equals(root.getTagName()) || root.getAttribute(\"namespace\").trim().isEmpty()) {\n    throw new IllegalStateException(\"Missing namespace in \" + xmlFile);\n}","typeGuard":null,"tryCatchPattern":"Not worth catching at runtime — this is a packaging defect. Catch at startup, log the resource path from the wrapping message, and fail the build/deploy.","preventionTips":["Add a CI/build check that validates mapper XMLs declare a namespace","Generate mapper XML from templates that always emit the namespace","Keep mapper-locations globs narrow (e.g. classpath*:mapper/**/*.xml)"],"tags":["mybatis","xml","mapper","parsing"],"backgroundTag":null,"analyzedSha":"bf67d907478c724120bf76292da54abf9e73c2b3","analyzedAt":"2026-08-14T15:17:09.543Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}