mybatis/mybatis-3 · error · BuilderException

Dots are not allowed in element names, please remove it from

Error message

Dots are not allowed in element names, please remove it from {base}

What it means

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.

Source

Thrown at src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java:103

    this.currentNamespace = currentNamespace;
  }

  public String applyCurrentNamespace(String base, boolean isReference) {
    if (base == null) {
      return null;
    }
    if (isReference) {
      // is it qualified with any namespace yet?
      if (base.contains(".")) {
        return base;
      }
    } else {
      // is it qualified with this namespace yet?
      if (base.startsWith(currentNamespace + ".")) {
        return base;
      }
      if (base.contains(".")) {
        throw new BuilderException("Dots are not allowed in element names, please remove it from " + base);
      }
    }
    return currentNamespace + "." + base;
  }

  public Cache useCacheRef(String namespace) {
    if (namespace == null) {
      throw new BuilderException("cache-ref element requires a namespace attribute.");
    }
    try {
      unresolvedCacheRef = true;
      Cache cache = configuration.getCache(namespace);
      if (cache == null) {
        throw new IncompleteElementException("No cache for namespace '" + namespace + "' could be found.");
      }
      currentCache = cache;
      unresolvedCacheRef = false;
      return cache;

View on GitHub (pinned to 008069adb1)

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

Example fix

<!-- before -->
<select id="find.user" resultType="User">...</select>
<!-- after -->
<select id="findUser" resultType="User">...</select>

Defensive patterns

Strategy: validation

Validate before calling

// Validate mapper element ids before parsing (XML or when building dynamically)
private static final Pattern VALID_ID = Pattern.compile("[A-Za-z_][A-Za-z0-9_]*");

void checkMapperIds(Document mapperXml) {
  NodeList ids = (NodeList) mapperXml.getElementsByTagNameNS("*", "*");
  for (int i = 0; i < ids.getLength(); i++) {
    Element e = (Element) ids.item(i);
    String id = e.getAttribute("id");
    if (!id.isEmpty() && id.contains(".")) {
      throw new IllegalStateException("Element <" + e.getTagName() + " id=\"" + id + "\"> must not contain dots");
    }
  }
}

Try / catch

try {
  sqlSessionFactory.build(inputStream);
} catch (BuilderException e) {
  if (e.getMessage().startsWith("Dots are not allowed")) {
    // surface the offending element name to CI output
    throw new ConfigurationException("Mapper id validation failed: " + e.getMessage(), e);
  }
  throw e;
}

Prevention

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)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/13fa8452197b0968. Report an issue: GitHub.