{"record":{"id":"13fa8452197b0968","repo":"mybatis/mybatis-3","slug":"dots-are-not-allowed-in-element-names-please-remo","errorCode":null,"errorMessage":"Dots are not allowed in element names, please remove it from {base}","messagePattern":"Dots are not allowed in element names, please remove it from (.+?)","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java","lineNumber":103,"sourceCode":"    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;\n      }\n    } else {\n      // is it qualified with this namespace yet?\n      if (base.startsWith(currentNamespace + \".\")) {\n        return base;\n      }\n      if (base.contains(\".\")) {\n        throw new BuilderException(\"Dots are not allowed in element names, please remove it from \" + base);\n      }\n    }\n    return currentNamespace + \".\" + base;\n  }\n\n  public Cache useCacheRef(String namespace) {\n    if (namespace == null) {\n      throw new BuilderException(\"cache-ref element requires a namespace attribute.\");\n    }\n    try {\n      unresolvedCacheRef = true;\n      Cache cache = configuration.getCache(namespace);\n      if (cache == null) {\n        throw new IncompleteElementException(\"No cache for namespace '\" + namespace + \"' could be found.\");\n      }\n      currentCache = cache;\n      unresolvedCacheRef = false;\n      return cache;","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java#L85-L121","documentation":"Thrown by MapperBuilderAssistant.applyCurrentNamespace() when a non-reference mapper element id (statement, resultMap, parameterMap, sql fragment) contains a dot ('.'). In MyBatis the dot is the namespace separator, so an id that is not already namespace-qualified but contains a dot is ambiguous and rejected. Reference-style ids (cache-ref, resultMap extends) are allowed to contain dots because they may point across namespaces.","triggerScenarios":"Defining <select id=\"find.user\">, <resultMap id=\"user.map\">, or <sql id=\"base.columns\"> in an XML mapper; also passing a dotted short id when calling assistant.applyCurrentNamespace(id, false) programmatically. Any mapper element whose id attribute has a '.' and which is not a cross-namespace reference hits this branch.","commonSituations":"Developers new to MyBatis try to use dotted names for readability (e.g. 'user.select') or copy ids from another framework's naming style; also happens when an id accidentally includes a package-like prefix instead of relying on the namespace attribute.","solutions":["Remove the dot from the element id, e.g. <select id=\"findUser\"> instead of <select id=\"find.user\">","If you intended a fully qualified reference, put the namespace in the <mapper namespace=\"...\"> attribute and reference elements as namespace.id from other mappers","If you meant to reference an element in another mapper (extends, cache-ref, resultMap refs), keep the dotted fully-qualified name but use it only where a reference is expected"],"exampleFix":"<!-- before -->\n<select id=\"find.user\" resultType=\"User\">...</select>\n<!-- after -->\n<select id=\"findUser\" resultType=\"User\">...</select>","handlingStrategy":"validation","validationCode":"// Validate mapper element ids before parsing (XML or when building dynamically)\nprivate static final Pattern VALID_ID = Pattern.compile(\"[A-Za-z_][A-Za-z0-9_]*\");\n\nvoid checkMapperIds(Document mapperXml) {\n  NodeList ids = (NodeList) mapperXml.getElementsByTagNameNS(\"*\", \"*\");\n  for (int i = 0; i < ids.getLength(); i++) {\n    Element e = (Element) ids.item(i);\n    String id = e.getAttribute(\"id\");\n    if (!id.isEmpty() && id.contains(\".\")) {\n      throw new IllegalStateException(\"Element <\" + e.getTagName() + \" id=\\\"\" + id + \"\\\"> must not contain dots\");\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  sqlSessionFactory.build(inputStream);\n} catch (BuilderException e) {\n  if (e.getMessage().startsWith(\"Dots are not allowed\")) {\n    // surface the offending element name to CI output\n    throw new ConfigurationException(\"Mapper id validation failed: \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Adopt a project convention of camelCase mapper ids and forbid dots in id attributes via lint/review","Only use dotted names where a cross-namespace reference is expected (extends, cache-ref, resultMap= in another mapper)"],"tags":["mybatis","xml-mapper","naming","configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}