{"record":{"id":"77569c5779090117","repo":"apache/beam","slug":"an-unsupported-type-of-cache-was-passed-in-received-s","errorCode":null,"errorMessage":"An unsupported type of cache was passed in. Received %s.","messagePattern":"An unsupported type of cache was passed in\\. Received (.+?)\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/harness/src/main/java/org/apache/beam/fn/harness/Caches.java","lineNumber":187,"sourceCode":"        ((long) options.as(SdkHarnessOptions.class).getMaxCacheMemoryUsageMb()) << 20);\n  }\n\n  /**\n   * Returns a view of a cache that operates on keys with a specified key prefix.\n   *\n   * <p>All lookups, insertions, and removals into the parent {@link Cache} will be prefixed by the\n   * specified prefixes.\n   */\n  public static <K, V> Cache<K, V> subCache(\n      Cache<?, ?> cache, Object keyPrefix, Object... additionalKeyPrefix) {\n    if (cache instanceof SubCache) {\n      return new SubCache<>(\n          ((SubCache<?, ?>) cache).cache,\n          ((SubCache<?, ?>) cache).keyPrefix.subKey(keyPrefix, additionalKeyPrefix),\n          ((SubCache<?, ?>) cache).maxWeightInBytes,\n          ((SubCache<?, ?>) cache).weightInBytes);\n    }\n    throw new IllegalArgumentException(\n        String.format(\n            \"An unsupported type of cache was passed in. Received %s.\",\n            cache == null ? \"null\" : cache.getClass()));\n  }\n\n  @VisibleForTesting\n  static <K, V> Cache<K, V> forMaximumBytes(long maximumBytes) {\n    // We specifically use Guava cache since it allows for recursive computeIfAbsent calls\n    // preventing deadlock from occurring when a loading function mutates the underlying cache\n    LongAdder weightInBytes = new LongAdder();\n    return new SubCache<>(\n        new ShrinkOnEviction(\n                CacheBuilder.newBuilder()\n                    .maximumWeight(maximumBytes >> WEIGHT_RATIO)\n                    .weigher(\n                        new Weigher<CompositeKey, WeightedValue<Object>>() {\n\n                          @Override","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/harness/src/main/java/org/apache/beam/fn/harness/Caches.java#L169-L205","documentation":"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.","triggerScenarios":"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).","commonSituations":"Custom Cache implementations handed into Beam's caching machinery; passing null; wrapping or decorating caches with non-SubCache adapters.","solutions":["Obtain the cache from Beam's Caches factory methods so it is a SubCache instance.","Null-check the cache before calling subCache — null is explicitly rejected.","Wrap your custom cache's contents into a Beam-managed cache instead of passing the adapter itself.","Read the message's class name to confirm which unexpected implementation was passed."],"exampleFix":"// before\nCaches.subCache(myCustomCache, \"prefix\", \"extra\");\n// after\nCache<?, ?> base = Caches.inMemoryCache();\nCaches.subCache(base, \"prefix\", \"extra\");","handlingStrategy":"type-guard","validationCode":"if (cache == null) throw new IllegalArgumentException(\"cache must be a Beam SubCache, not null\");","typeGuard":"boolean isSubCache(Cache<?, ?> c) { return c instanceof Caches.SubCache; }","tryCatchPattern":"try {\n  return Caches.subCache(cache, prefix, extraPrefix);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"unsupported type of cache\")) { /* use Beam factory cache */ }\n  throw e;\n}","preventionTips":["Only pass caches created by Caches factory methods into subCache","Null-check caches before handing them to harness internals","Avoid wrapping harness caches in custom adapter classes"],"tags":["apache-beam","java","fn-harness","cache","type-cast"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}