mybatis/mybatis-3 · error · CacheException

Failed cache initialization for '{}' on '{}'

Error message

Failed cache initialization for '{}' on '{}'

What it means

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.

Source

Thrown at src/main/java/org/apache/ibatis/mapping/CacheBuilder.java:176

          } else if (byte.class == type || Byte.class == type) {
            metaCache.setValue(name, Byte.valueOf(value));
          } else if (float.class == type || Float.class == type) {
            metaCache.setValue(name, Float.valueOf(value));
          } else if (boolean.class == type || Boolean.class == type) {
            metaCache.setValue(name, Boolean.valueOf(value));
          } else if (double.class == type || Double.class == type) {
            metaCache.setValue(name, Double.valueOf(value));
          } else {
            throw new CacheException("Unsupported property type for cache: '" + name + "' of type " + type);
          }
        }
      }
    }
    if (InitializingObject.class.isAssignableFrom(cache.getClass())) {
      try {
        ((InitializingObject) cache).initialize();
      } catch (Exception e) {
        throw new CacheException(
            "Failed cache initialization for '" + cache.getId() + "' on '" + cache.getClass().getName() + "'", e);
      }
    }
  }

  private Cache newBaseCacheInstance(Class<? extends Cache> cacheClass, String id) {
    Constructor<? extends Cache> cacheConstructor = getBaseCacheConstructor(cacheClass);
    try {
      return cacheConstructor.newInstance(id);
    } catch (Exception e) {
      throw new CacheException("Could not instantiate cache implementation (" + cacheClass + "). Cause: " + e, e);
    }
  }

  private Constructor<? extends Cache> getBaseCacheConstructor(Class<? extends Cache> cacheClass) {
    try {
      return cacheClass.getConstructor(String.class);
    } catch (Exception e) {

View on GitHub (pinned to 008069adb1)

Solutions

1. Read the chained cause — it is the exception your initialize() threw; fix that root problem (start the server, fix credentials).
2. Ensure all required <property> entries for the cache are present in the mapper's <cache> element before initialization runs.
3. Defer network connections out of initialize() (lazy-connect on first use) so a temporarily unavailable server does not kill SqlSessionFactory creation.

// Fail fast on required properties before MyBatis initializes the cache
if (cacheConfig.get("host") == null) {
  throw new IllegalStateException("cache 'host' property required for " + cacheId);
}

try {
  sqlSessionFactory = new SqlSessionFactoryBuilder().build(reader);
} catch (CacheException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Failed cache initialization")) {
    // surface as configuration error with the cache id/class from the message
    throw new ConfigurationException("Remote cache unavailable at startup: " + e.getMessage(), e);
  }
  throw e;
}

When it happens

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

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

Related errors

• Could not instantiate cache implementation ({}). Cause: {}
• Invalid base cache implementation ({}). Base cache implemen
• cache-ref element requires a namespace attribute.
• No cache for namespace '{namespace}' could be found.
• Cache-ref not yet resolved

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