What causes "Could not instantiate cache decorator ({}). Cause: {}" in mybatis/mybatis-3?

Inspect the chained cause and fix the exception thrown inside the decorator constructor.

mybatis/mybatis-3 · error · CacheException

Could not instantiate cache decorator ({}). Cause: {}

Error message

Could not instantiate cache decorator ({}). Cause: {}

What it means

CacheBuilder.newCacheDecoratorInstance() throws CacheException when a cache decorator's constructor Cache(Cache delegate) was located but newInstance(base) failed — the decorator constructor threw or the class could not be initialized. The decorator class and cause are included.

Source

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

    }
  }

  private Constructor<? extends Cache> getBaseCacheConstructor(Class<? extends Cache> cacheClass) {
    try {
      return cacheClass.getConstructor(String.class);
    } catch (Exception e) {
      throw new CacheException("Invalid base cache implementation (" + cacheClass + ").  "
          + "Base cache implementations must have a constructor that takes a String id as a parameter.  Cause: " + e,
          e);
    }
  }

  private Cache newCacheDecoratorInstance(Class<? extends Cache> cacheClass, Cache base) {
    Constructor<? extends Cache> cacheConstructor = getCacheDecoratorConstructor(cacheClass);
    try {
      return cacheConstructor.newInstance(base);
    } catch (Exception e) {
      throw new CacheException("Could not instantiate cache decorator (" + cacheClass + "). Cause: " + e, e);
    }
  }

  private Constructor<? extends Cache> getCacheDecoratorConstructor(Class<? extends Cache> cacheClass) {
    try {
      return cacheClass.getConstructor(Cache.class);
    } catch (Exception e) {
      throw new CacheException("Invalid cache decorator (" + cacheClass + ").  "
          + "Cache decorators must have a constructor that takes a Cache instance as a parameter.  Cause: " + e, e);
    }
  }
}

View on GitHub (pinned to 008069adb1)

Solutions

Inspect the chained cause and fix the exception thrown inside the decorator constructor.
Keep decorator constructors side-effect free: only store the delegate; do work lazily.
Verify the decorator is designed for the delegate it wraps (check delegate type/interfaces before use).

Defensive patterns

Strategy: try-catch

Try / catch

try {
  Cache decorated = new CacheBuilder(id).implementation(MyCache.class)
      .addDecorator(MyDecorator.class).build();
} catch (CacheException e) {
  throw new ConfigurationException("Decorator failed: " + e.getCause(), e);
}

Prevention

Decorator constructors must only store the delegate — no validation that throws, no resource acquisition.
Unit-test each decorator wrapping the exact base cache class used in production.
Check the chained cause first; it distinguishes constructor bugs from configuration issues.

When it happens

Trigger: A custom decorator listed in <cache-ref>/CacheBuilder.addDecorator (or the standard decorator chain) whose constructor throws, e.g. allocating resources based on the delegate's configuration.

Common situations: Custom decorator implementations that validate the delegate cache in the constructor and reject it (e.g. requires a TransactionalCache but receives a plain one); decorators with side effects (metrics registration) failing in constrained environments.

Related errors

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