apache/druid · error · IllegalStateException

Doesn't make sense to use Hybrid cache with both use and…

Error message

Doesn't make sense to use Hybrid cache with both use and populate disabled for L2, use just L1 cache in this case

What it means

HybridCacheProvider combines an L1 (on-heap) and L2 (off-heap/remote) cache. Its constructor validates that at least one of useL2 or populateL2 is enabled; if both are false, an L2 tier is pointless, so it throws IllegalStateException telling you to use just L1.

Solutions

Set level2.use=true (and level2.populate=true if writes are desired) in cache config
Switch druid.cache.type to the L1 type (e.g. caffeine) and drop the hybrid configuration entirely
Verify the L2 provider (e.g. memcached/redis) config keys are present and correctly named
Remove the hybrid wiring if L2 is genuinely not wanted

Example fix

// before
{"type": "hybrid", "l1": {...}, "l2": {"use": false, "populate": false}} // ISE
// after
{"type": "hybrid", "l1": {...}, "l2": {"use": true, "populate": true}}

Defensive patterns

Strategy: validation

Validate before calling

if ("hybrid".equals(cacheType) && !l2Use && !l2Populate) {
  throw new IllegalArgumentException("hybrid cache requires level2.use or level2.populate");
}

Prevention

Enable level2.use when using hybrid cache
Prefer plain L1 cache type when L2 is not needed
Double-check L2 config keys survive upgrades

When it happens

Trigger: Constructing a hybrid cache where level2.use/level2.populate flags are both false (or default to false and unset) while still configuring a hybrid provider.

Common situations: Setting druid.cache.type=hybrid but omitting the L2 use/populate flags (which default to false); copy-pasted config where L2 toggles were disabled; upgrade where flag names changed and L2 settings silently dropped.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/4e08bd372f67864a. Report an issue: GitHub.

Appendix: source

Thrown at server/src/main/java/org/apache/druid/client/cache/HybridCacheProvider.java:41

import com.fasterxml.jackson.annotation.JsonCreator;
import com.google.common.base.Preconditions;
import com.google.inject.name.Named;

public class HybridCacheProvider extends HybridCacheConfig implements CacheProvider
{
  final CacheProvider level1;
  final CacheProvider level2;

  @JsonCreator
  public HybridCacheProvider(
      @JacksonInject @Named("l1") CacheProvider level1,
      @JacksonInject @Named("l2") CacheProvider level2
  )
  {
    this.level1 = Preconditions.checkNotNull(level1, "l1 cache not specified for hybrid cache");
    this.level2 = Preconditions.checkNotNull(level2, "l2 cache not specified for hybrid cache");
    if (!getUseL2() && !getPopulateL2()) {
      throw new IllegalStateException(
          "Doesn't make sense to use Hybrid cache with both use and populate disabled for L2, "
          + "use just L1 cache in this case"
      );
    }
  }

  @Override
  public Cache get()
  {
    return new HybridCache(this, level1.get(), level2.get());
  }
}

View on GitHub (pinned to 9b90983fd2)