{"record":{"id":"18b4e707503582c6","repo":"mybatis/mybatis-3","slug":"no-cache-for-namespace-namespace-could-be-foun","errorCode":null,"errorMessage":"No cache for namespace '{namespace}' could be found.","messagePattern":"No cache for namespace '(.+?)' could be found\\.","errorType":"exception","errorClass":"IncompleteElementException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java","lineNumber":117,"sourceCode":"      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))\n        .addDecorator(valueOrDefault(evictionClass, LruCache.class)).clearInterval(flushInterval).size(size)\n        .readWrite(readWrite).blocking(blocking).properties(props).build();\n    configuration.addCache(cache);\n    currentCache = cache;\n    return cache;\n  }","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java#L99-L135","documentation":"Thrown by useCacheRef() when configuration.getCache(namespace) returns null: the target namespace has no cache registered yet. Unlike a plain BuilderException, this is an IncompleteElementException, signaling MyBatis that the mapper may simply be parsed before the cache-defining mapper, so parsing is retried after all mappers are loaded.","triggerScenarios":"<cache-ref namespace=\"X\"/> where mapper X has no <cache> element at all, or where X is parsed after the referencing mapper (normal cross-mapper ordering). Also triggered from @CacheNamespaceRef parsing in MapperAnnotationBuilder.parseCacheRef().","commonSituations":"Referencing a mapper that never declared <cache>/@CacheNamespace (the ref is genuinely dangling), or ordering issues during configuration that resolve themselves on the second pass — a hard failure only appears if the cache never materializes.","solutions":["Verify the target mapper declares a cache: add <cache/> (or a customized <cache type=... eviction=.../>) to the referenced XML mapper, or @CacheNamespace on the referenced interface","Double-check the namespace string matches the referenced mapper's namespace attribute exactly (fully qualified, case-sensitive)","If the error persists after all mappers are loaded, the referenced namespace is misspelled or its mapper is not registered in mybatis-config.xml / being scanned"],"exampleFix":"<!-- before: UserMapper has cache-ref but RoleMapper has no cache -->\n<cache-ref namespace=\"com.acme.RoleMapper\"/>\n<!-- after: add to RoleMapper.xml -->\n<cache eviction=\"LRU\" flushInterval=\"60000\" size=\"512\" readOnly=\"true\"/>","handlingStrategy":"validation","validationCode":"// Before SqlSessionFactory build: verify every cache-ref namespace has a cache owner\nSet<String> cacheOwners = new HashSet<>();\n// collect namespaces of mappers that declare <cache> or @CacheNamespace\nfor (MapperMetadata m : allMappers) {\n  if (m.declaresCache()) cacheOwners.add(m.getNamespace());\n}\nfor (String refNs : collectCacheRefNamespaces()) {\n  if (!cacheOwners.contains(refNs)) throw new IllegalStateException(\"cache-ref target has no cache: \" + refNs);\n}","typeGuard":null,"tryCatchPattern":"try {\n  session.getConfiguration().getCache(refNamespace);\n} catch (Exception e) {\n  // treat as configuration bug, not runtime: fail startup loudly\n  throw new IllegalStateException(\"cache-ref target missing: \" + refNamespace, e);\n}","preventionTips":["Define the <cache> element in one shared/base mapper and reference it consistently","Add a startup assertion that walks all cache-ref targets and confirms each namespace has a cache","Keep namespaces identical to fully-qualified interface names so refactors break compilation, not runtime"],"tags":["mybatis","cache","cache-ref","incomplete-element"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}