apache/beam · error · IllegalArgumentException

An unsupported type of cache was passed in. Received %s.

Error message

An unsupported type of cache was passed in. Received %s.

What it means

Caches.subCache derives a namespaced sub-cache by downcasting the given cache to the internal SubCache type, reusing its underlying map, key prefix, and byte accounting. If the supplied cache is not a SubCache (or is null), the cast is impossible and IllegalArgumentException is thrown describing the received type.

Source

Thrown at sdks/java/harness/src/main/java/org/apache/beam/fn/harness/Caches.java:187

        ((long) options.as(SdkHarnessOptions.class).getMaxCacheMemoryUsageMb()) << 20);
  }

  /**
   * Returns a view of a cache that operates on keys with a specified key prefix.
   *
   * <p>All lookups, insertions, and removals into the parent {@link Cache} will be prefixed by the
   * specified prefixes.
   */
  public static <K, V> Cache<K, V> subCache(
      Cache<?, ?> cache, Object keyPrefix, Object... additionalKeyPrefix) {
    if (cache instanceof SubCache) {
      return new SubCache<>(
          ((SubCache<?, ?>) cache).cache,
          ((SubCache<?, ?>) cache).keyPrefix.subKey(keyPrefix, additionalKeyPrefix),
          ((SubCache<?, ?>) cache).maxWeightInBytes,
          ((SubCache<?, ?>) cache).weightInBytes);
    }
    throw new IllegalArgumentException(
        String.format(
            "An unsupported type of cache was passed in. Received %s.",
            cache == null ? "null" : cache.getClass()));
  }

  @VisibleForTesting
  static <K, V> Cache<K, V> forMaximumBytes(long maximumBytes) {
    // We specifically use Guava cache since it allows for recursive computeIfAbsent calls
    // preventing deadlock from occurring when a loading function mutates the underlying cache
    LongAdder weightInBytes = new LongAdder();
    return new SubCache<>(
        new ShrinkOnEviction(
                CacheBuilder.newBuilder()
                    .maximumWeight(maximumBytes >> WEIGHT_RATIO)
                    .weigher(
                        new Weigher<CompositeKey, WeightedValue<Object>>() {

                          @Override

View on GitHub (pinned to 12126d8942)

Solutions

1. Obtain the cache from Beam's Caches factory methods so it is a SubCache instance.
2. Null-check the cache before calling subCache — null is explicitly rejected.
3. Wrap your custom cache's contents into a Beam-managed cache instead of passing the adapter itself.
4. Read the message's class name to confirm which unexpected implementation was passed.

Example fix

// before
Caches.subCache(myCustomCache, "prefix", "extra");
// after
Cache<?, ?> base = Caches.inMemoryCache();
Caches.subCache(base, "prefix", "extra");

if (cache == null) throw new IllegalArgumentException("cache must be a Beam SubCache, not null");

boolean isSubCache(Cache<?, ?> c) { return c instanceof Caches.SubCache; }

try {
  return Caches.subCache(cache, prefix, extraPrefix);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("unsupported type of cache")) { /* use Beam factory cache */ }
  throw e;
}

When it happens

Trigger: Passing a user-supplied Cache implementation (or null) into Caches.subCache instead of a cache obtained from Caches' own factory (e.g. from Caches.inMemory() / elsewhere in the harness).

Common situations: Custom Cache implementations handed into Beam's caching machinery; passing null; wrapping or decorating caches with non-SubCache adapters.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Internal error initializing BeamFnDataReadRunner: invalid mo
• Timing number 0b" + timingNumber.toString(2) + " has more th
• No proto encoding for PaneInfoCoder, always part of Windowed
• Runner does not support draining.
• cannot encode a null Integer

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/77569c5779090117. Report an issue: GitHub.