What causes "Error building standard cache decorators. Cause: {}" in mybatis/mybatis-3?

Inspect the chained cause — the underlying exception identifies the failing decorator or property.

mybatis/mybatis-3 · error · CacheException

Error building standard cache decorators. Cause: {}

Error message

Error building standard cache decorators.  Cause: {}

What it means

CacheBuilder.build() wraps its whole decorator-stack construction (FifoCache/LruCache/ScheduledCache/SerializedCache/LoggingCache/SynchronizedCache/BlockingCache plus property setting) in a try/catch and rethrows any Exception as CacheException with this message. It is a catch-all: reflection failures, property conversion errors, or cache implementation exceptions during build surface here.

Source

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

      MetaObject metaCache = SystemMetaObject.forObject(cache);
      if (size != null && metaCache.hasSetter("size")) {
        metaCache.setValue("size", size);
      }
      if (clearInterval != null) {
        cache = new ScheduledCache(cache);
        ((ScheduledCache) cache).setClearInterval(clearInterval);
      }
      if (readWrite) {
        cache = new SerializedCache(cache);
      }
      cache = new LoggingCache(cache);
      cache = new SynchronizedCache(cache);
      if (blocking) {
        cache = new BlockingCache(cache);
      }
      return cache;
    } catch (Exception e) {
      throw new CacheException("Error building standard cache decorators.  Cause: " + e, e);
    }
  }

  private void setCacheProperties(Cache cache) {
    if (properties != null) {
      MetaObject metaCache = SystemMetaObject.forObject(cache);
      for (Map.Entry<Object, Object> entry : properties.entrySet()) {
        String name = (String) entry.getKey();
        String value = (String) entry.getValue();
        if (metaCache.hasSetter(name)) {
          Class<?> type = metaCache.getSetterType(name);
          if (String.class == type) {
            metaCache.setValue(name, value);
          } else if (int.class == type || Integer.class == type) {
            metaCache.setValue(name, Integer.valueOf(value));
          } else if (long.class == type || Long.class == type) {
            metaCache.setValue(name, Long.valueOf(value));
          } else if (short.class == type || Short.class == type) {

View on GitHub (pinned to 008069adb1)

Solutions

Inspect the chained cause — the underlying exception identifies the failing decorator or property.
If the cause mentions a property, fix the <cache> attributes (names/types must match the cache implementation's setters).
If the cause is instantiation-related, verify the cache class has the required constructors (String id, and Cache for decorators).
Simplify: temporarily remove custom attributes/decorators (readWrite, blocking, eviction) and add them back one at a time to isolate the failing setting.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  Cache cache = new CacheBuilder(id).implementation(MyCache.class).build();
} catch (CacheException e) {
  throw new ConfigurationException("Cache '" + id + "' misconfigured: " + e.getCause(), e);
}

Prevention

Build custom caches first in a unit test with the same <cache> attributes as production XML.
Keep attribute names/types aligned with the cache implementation's setters (primitive/String only).
Add the custom cache configuration to integration tests so it is exercised at every build.

When it happens

Trigger: Building a cache via <cache type="..."/> or CacheBuilder where any decorator step throws: a setCacheProperties conversion failure, cache class instantiation failure, ScheduledCache with bad clearInterval, or SerializedCache on a non-Serializable model class hit later during build-time checks.

Common situations: Custom cache implementations in mapper XML; eviction/clearInterval attributes typo'd or wrong units; readWrite=true with non-Serializable cached objects; decorator constructors throwing under different MyBatis versions.

Related errors

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