{"record":{"id":"c4127fdd2e90b97c","repo":"mybatis/mybatis-3","slug":"the-mapper-element-requires-a-namespace-attribute","errorCode":null,"errorMessage":"The mapper element requires a namespace attribute to be specified.","messagePattern":"The mapper element requires a namespace attribute to be specified\\.","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java","lineNumber":77,"sourceCode":"\n  private String currentNamespace;\n  private final String resource;\n  private Cache currentCache;\n  private boolean unresolvedCacheRef; // issue #676\n\n  public MapperBuilderAssistant(Configuration configuration, String resource) {\n    super(configuration);\n    ErrorContext.instance().resource(resource);\n    this.resource = resource;\n  }\n\n  public String getCurrentNamespace() {\n    return currentNamespace;\n  }\n\n  public void setCurrentNamespace(String currentNamespace) {\n    if (currentNamespace == null) {\n      throw new BuilderException(\"The mapper element requires a namespace attribute to be specified.\");\n    }\n\n    if (this.currentNamespace != null && !this.currentNamespace.equals(currentNamespace)) {\n      throw new BuilderException(\n          \"Wrong namespace. Expected '\" + this.currentNamespace + \"' but found '\" + currentNamespace + \"'.\");\n    }\n\n    this.currentNamespace = currentNamespace;\n  }\n\n  public String applyCurrentNamespace(String base, boolean isReference) {\n    if (base == null) {\n      return null;\n    }\n    if (isReference) {\n      // is it qualified with any namespace yet?\n      if (base.contains(\".\")) {\n        return base;","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java#L59-L95","documentation":"MapperBuilderAssistant.setCurrentNamespace(null) is called when an XML mapper element carries no namespace attribute. Since every statement id is namespaced as 'namespace.id', a mapper without a namespace cannot be bound, so parsing aborts with this BuilderException.","triggerScenarios":"A mapper XML file whose root element is <mapper> without the namespace attribute; dynamically generated mapper XML omitting the attribute; DTD-valid file but namespace lost during templating/merge.","commonSituations":"Hand-writing a new mapper file from a template that lacks the attribute; code-generation templates with an unfilled ${namespace} placeholder; refactoring that accidentally deletes the attribute.","solutions":["Add namespace=\"fully.qualified.MapperInterface\" to the root <mapper> element","If the file is generated, fix the template so the namespace placeholder is populated"],"exampleFix":"<!-- before -->\n<mapper>\n  <select id=\"find\" ...>\n<!-- after -->\n<mapper namespace=\"com.example.UserMapper\">\n  <select id=\"find\" ...>","handlingStrategy":"validation","validationCode":"// in build/CI: parse each mapper XML and assert the root attribute\n// Document d = parse(file); d.getDocumentElement().getAttribute(\"namespace\").isBlank() -> fail","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always start new mapper files from a template containing the namespace attribute","Validate generated XML in CI with a DTD/XSD check plus a parse smoke test"],"tags":["mybatis","builder","namespace","xml-configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}