{"record":{"id":"ae0f0a3762904cb0","repo":"mybatis/mybatis-3","slug":"failed-cache-initialization-for-on","errorCode":null,"errorMessage":"Failed cache initialization for '{}' on '{}'","messagePattern":"Failed cache initialization for '(.+?)' on '(.+?)'","errorType":"exception","errorClass":"CacheException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/mapping/CacheBuilder.java","lineNumber":176,"sourceCode":"          } else if (byte.class == type || Byte.class == type) {\n            metaCache.setValue(name, Byte.valueOf(value));\n          } else if (float.class == type || Float.class == type) {\n            metaCache.setValue(name, Float.valueOf(value));\n          } else if (boolean.class == type || Boolean.class == type) {\n            metaCache.setValue(name, Boolean.valueOf(value));\n          } else if (double.class == type || Double.class == type) {\n            metaCache.setValue(name, Double.valueOf(value));\n          } else {\n            throw new CacheException(\"Unsupported property type for cache: '\" + name + \"' of type \" + type);\n          }\n        }\n      }\n    }\n    if (InitializingObject.class.isAssignableFrom(cache.getClass())) {\n      try {\n        ((InitializingObject) cache).initialize();\n      } catch (Exception e) {\n        throw new CacheException(\n            \"Failed cache initialization for '\" + cache.getId() + \"' on '\" + cache.getClass().getName() + \"'\", e);\n      }\n    }\n  }\n\n  private Cache newBaseCacheInstance(Class<? extends Cache> cacheClass, String id) {\n    Constructor<? extends Cache> cacheConstructor = getBaseCacheConstructor(cacheClass);\n    try {\n      return cacheConstructor.newInstance(id);\n    } catch (Exception e) {\n      throw new CacheException(\"Could not instantiate cache implementation (\" + cacheClass + \"). Cause: \" + e, e);\n    }\n  }\n\n  private Constructor<? extends Cache> getBaseCacheConstructor(Class<? extends Cache> cacheClass) {\n    try {\n      return cacheClass.getConstructor(String.class);\n    } catch (Exception e) {","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/mapping/CacheBuilder.java#L158-L194","documentation":"CacheBuilder.setCacheProperties() calls initialize() on cache implementations implementing InitializingObject after applying properties; any Exception from initialize() is rethrown as CacheException naming the cache id and class. It means the cache itself rejected its configuration at startup.","triggerScenarios":"A custom Cache class implementing InitializingObject whose initialize() throws: connecting to a remote cache server (Redis/Memcached) that is unreachable, validating properties and finding an invalid combination, or resource allocation failure.","commonSituations":"Custom distributed-cache adapters whose initialize() opens network connections; missing required property because the XML <property> was forgotten; remote server down when the SqlSessionFactory is built (often at application startup).","solutions":["Read the chained cause — it is the exception your initialize() threw; fix that root problem (start the server, fix credentials).","Ensure all required <property> entries for the cache are present in the mapper's <cache> element before initialization runs.","Defer network connections out of initialize() (lazy-connect on first use) so a temporarily unavailable server does not kill SqlSessionFactory creation."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Fail fast on required properties before MyBatis initializes the cache\nif (cacheConfig.get(\"host\") == null) {\n  throw new IllegalStateException(\"cache 'host' property required for \" + cacheId);\n}","typeGuard":null,"tryCatchPattern":"try {\n  sqlSessionFactory = new SqlSessionFactoryBuilder().build(reader);\n} catch (CacheException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Failed cache initialization\")) {\n    // surface as configuration error with the cache id/class from the message\n    throw new ConfigurationException(\"Remote cache unavailable at startup: \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Do not open network connections in initialize(); connect lazily on first cache access.","Validate required properties yourself before SqlSessionFactory is built.","Make external cache servers a startup precondition (health check) so failure is diagnosed as infra, not MyBatis."],"tags":["mybatis","cache","initialization","custom-cache"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}