{"record":{"id":"d008aff1edcd2330","repo":"mybatis/mybatis-3","slug":"cache-ref-element-requires-a-namespace-attribute","errorCode":null,"errorMessage":"cache-ref element requires a namespace attribute.","messagePattern":"cache-ref element requires a namespace attribute\\.","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java","lineNumber":111,"sourceCode":"      // 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;\n    } catch (IllegalArgumentException e) {\n      throw new IncompleteElementException(\"No cache for namespace '\" + namespace + \"' could be found.\", e);\n    }\n  }\n\n  public Cache useNewCache(Class<? extends Cache> typeClass, Class<? extends Cache> evictionClass, Long flushInterval,\n      Integer size, boolean readWrite, boolean blocking, Properties props) {\n    Cache cache = new CacheBuilder(currentNamespace).implementation(valueOrDefault(typeClass, PerpetualCache.class))","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java#L93-L129","documentation":"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.","triggerScenarios":"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).","commonSituations":"Typos like <cache-ref namescape=\"...\">, forgetting the attribute when copy-pasting a cache-ref block, or hand-rolling annotation/XML parsing that passes null.","solutions":["Add the namespace attribute pointing at the mapper that declares the <cache> element: <cache-ref namespace=\"com.acme.UserMapper\"/>","Ensure the referenced mapper actually declares a <cache> element; cache-ref alone does not create a cache","If using annotations, use @CacheNamespaceRef(value = OtherMapper.class) or @CacheNamespaceRef(name = \"com.acme.OtherMapper\")"],"exampleFix":"<!-- before -->\n<cache-ref/>\n<!-- after -->\n<cache-ref namespace=\"com.acme.UserMapper\"/>","handlingStrategy":"validation","validationCode":"// Before building, ensure every <cache-ref> element has a namespace attribute\nNodeList cacheRefs = mapperXml.getElementsByTagName(\"cache-ref\");\nfor (int i = 0; i < cacheRefs.getLength(); i++) {\n  if (cacheRefs.item(i).getAttributes().getNamedItem(\"namespace\") == null) {\n    throw new IllegalStateException(\"<cache-ref> without namespace attribute at \" + cacheRefs.item(i));\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add an XML schema (DTD/XSD) check to CI so a missing required attribute fails fast with a clear location","Review cache-ref elements whenever copy-pasting mapper boilerplate"],"tags":["mybatis","cache","xml-mapper","configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}