mybatis/mybatis-3 · error · BuilderException

cache-ref element requires a namespace attribute.

Error message

cache-ref element requires a namespace attribute.

What it means

Thrown by MapperBuilderAssistant.useCacheRef() when it is called with a null namespace. A <cache-ref> element in an XML mapper must carry a namespace attribute naming the mapper whose cache should be shared; the API enforces this at parse time with a BuilderException.

Source

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

      // 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;
    } catch (IllegalArgumentException e) {
      throw new IncompleteElementException("No cache for namespace '" + namespace + "' could be found.", e);
    }
  }

  public Cache useNewCache(Class<? extends Cache> typeClass, Class<? extends Cache> evictionClass, Long flushInterval,
      Integer size, boolean readWrite, boolean blocking, Properties props) {
    Cache cache = new CacheBuilder(currentNamespace).implementation(valueOrDefault(typeClass, PerpetualCache.class))

View on GitHub (pinned to 008069adb1)

Solutions

1. Add the namespace attribute pointing at the mapper that declares the <cache> element: <cache-ref namespace="com.acme.UserMapper"/>
2. Ensure the referenced mapper actually declares a <cache> element; cache-ref alone does not create a cache
3. If using annotations, use @CacheNamespaceRef(value = OtherMapper.class) or @CacheNamespaceRef(name = "com.acme.OtherMapper")

Example fix

<!-- before -->
<cache-ref/>
<!-- after -->
<cache-ref namespace="com.acme.UserMapper"/>

// Before building, ensure every <cache-ref> element has a namespace attribute
NodeList cacheRefs = mapperXml.getElementsByTagName("cache-ref");
for (int i = 0; i < cacheRefs.getLength(); i++) {
  if (cacheRefs.item(i).getAttributes().getNamedItem("namespace") == null) {
    throw new IllegalStateException("<cache-ref> without namespace attribute at " + cacheRefs.item(i));
  }
}

When it happens

Trigger: Writing <cache-ref/> with no namespace attribute in an XML mapper file, or calling assistant.useCacheRef(null) directly (e.g. from a custom builder or plugin).

Common situations: Typos like <cache-ref namescape="...">, forgetting the attribute when copy-pasting a cache-ref block, or hand-rolling annotation/XML parsing that passes null.

Related errors

• Dots are not allowed in element names, please remove it from
• Should be specified either value() or name() attribute in th
• Cannot use both value() and name() attribute in the @CacheNa
• Error building standard cache decorators. Cause: {}
• Unsupported property type for cache: '{}' of type {}

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