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

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.

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.

Appendix: 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)