quarkusio/quarkus · error · IllegalStateException

Weigher class ' ' must implement…

Error message

Weigher class '<className>' must implement com.github.benmanes.caffeine.cache.Weigher

What it means

When a 2nd-level cache region is configured with a custom Caffeine weigher, QuarkusPersistenceUnitCaffeineCacheManager.instantiateWeigher() loads the class by name and verifies it implements com.github.benmanes.caffeine.cache.Weigher. If the loaded class does not implement that interface, an IllegalStateException is thrown, failing persistence unit startup.

Solutions

  1. Make the configured class implement com.github.benmanes.caffeine.cache.Weigher<K,V> (and its weigh method returning a positive int).
  2. Verify the fully-qualified class name in the config points to the intended weigher class, not a similarly named other class.
  3. If you don't need weighted eviction, remove the weigher setting so Caffeine's default counting-based eviction is used.
  4. Give the weigher class a public no-arg constructor so it can also pass the subsequent instantiation step.

Example fix

// before
class MyWeigher { public int weigh(Object k, Object v) { return 1; } }

// after
import com.github.benmanes.caffeine.cache.Weigher;
class MyWeigher implements Weigher<Object, Object> {
  public int weigh(Object k, Object v) { return 1; }
}
Defensive patterns

Strategy: validation

Validate before calling

// Validate the weigher class before setting it in config
Class<?> c = Class.forName(weigherClassName);
if (!com.github.benmanes.caffeine.cache.Weigher.class.isAssignableFrom(c)) {
    throw new IllegalStateException(weigherClassName + " does not implement Caffeine Weigher");
}

Type guard

static boolean isValidWeigher(Class<?> c) {
    return c != null
        && com.github.benmanes.caffeine.cache.Weigher.class.isAssignableFrom(c);
}

Try / catch

try {
    startPu();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("must implement com.github.benmanes.caffeine.cache.Weigher")) {
        log.error("Fix or remove quarkus.hibernate-orm.cache.<name>.weigher config", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Setting a cache region weigher class name (e.g. via quarkus.hibernate-orm.cache.<cache>.weigher or Hibernate cache config) where the class exists on the classpath but does not implement com.github.benmanes.caffeine.cache.Weigher.

Common situations: Pointing the weigher property at a Comparator, a CacheLoader, or a custom class that implements weigh() without implementing the Weigher interface; copying a class from an example that used a different caching abstraction; class name typos resolved to an unrelated same-named class.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/7cc368190d00c7c2. Report an issue: GitHub.

Appendix: source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/cache/QuarkusPersistenceUnitCaffeineCacheManager.java:114

            if (quarkusConfig.hasWeigherClass()) {
                Weigher<K, V> weigher = instantiateWeigher(quarkusConfig.weigherClassName());
                caffeineConfig.setWeigherFactory(Optional.of(() -> weigher));
            }
        } else {
            // Count-based eviction (default)
            caffeineConfig.setMaximumSize(OptionalLong.of(quarkusConfig.maxSize()));
        }

        caffeineConfig.setExpireAfterAccess(OptionalLong.of(quarkusConfig.maxIdle().toNanos()));
        return delegate.createCache(cacheName, caffeineConfig);
    }

    @SuppressWarnings("unchecked")
    private <K, V> Weigher<K, V> instantiateWeigher(String className) {
        try {
            Class<?> weigherClass = Thread.currentThread().getContextClassLoader().loadClass(className);
            if (!Weigher.class.isAssignableFrom(weigherClass)) {
                throw new IllegalStateException(
                        "Weigher class '" + className + "' must implement com.github.benmanes.caffeine.cache.Weigher");
            }
            return (Weigher<K, V>) weigherClass.getConstructor().newInstance();
        } catch (IllegalStateException e) {
            throw e;
        } catch (Exception e) {
            throw new IllegalStateException("Unable to instantiate weigher class: " + className, e);
        }
    }

    @Override
    public Iterable<String> getCacheNames() {
        return delegate.getCacheNames();
    }

    @Override
    public void destroyCache(String cacheName) {
        throw new UnsupportedOperationException("This should not be used by Hibernate ORM");

View on GitHub (pinned to e1c734241f)