{"record":{"id":"9b093e9d9ed87cb5","repo":"apache/beam","slug":"unknown-state-key-type-requested-s","errorCode":null,"errorMessage":"Unknown state key type requested %s.","messagePattern":"Unknown state key type requested (.+?)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/FnApiStateAccessor.java","lineNumber":1190,"sourceCode":"          if (!token.hasSideInput()) {\n            continue;\n          }\n          if (stateKey\n                  .getMultimapKeysSideInput()\n                  .getTransformId()\n                  .equals(token.getSideInput().getTransformId())\n              && stateKey\n                  .getMultimapKeysSideInput()\n                  .getSideInputId()\n                  .equals(token.getSideInput().getSideInputId())) {\n            // IDEA: If cachetoken shows up on profiles, create a simpler type to weigh like\n            // UserStateCacheTokenKey.\n            return Caches.subCache(processWideCache, token, stateKey);\n          }\n        }\n        break;\n      default:\n        throw new IllegalStateException(\n            String.format(\"Unknown state key type requested %s.\", stateKey));\n    }\n    // The default is to use the bundle cache.\n    return Caches.subCache(bundleCache.get(), stateKey);\n  }\n\n  private <T> BagUserState<T> createBagUserState(StateKey stateKey, Coder<T> valueCoder) {\n    BagUserState<T> rval =\n        new BagUserState<>(\n            getCacheFor(stateKey),\n            beamFnStateClient,\n            processBundleInstructionId.get(),\n            stateKey,\n            valueCoder);\n    stateFinalizers.add(rval::asyncClose);\n    return rval;\n  }\n","sourceCodeStart":1172,"sourceCodeEnd":1208,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/FnApiStateAccessor.java#L1172-L1208","documentation":"FnApiStateAccessor's cache selection logic switches over the StateKey protocol type to decide which cache (process-wide vs bundle) backs a state cell. If the StateKey oneof is a type it does not recognize, it throws this IllegalStateException with the key's string form. This means the runner sent a state key type the harness cannot cache.","triggerScenarios":"The runner issues a state request whose StateKey is not one of the handled types (bag, multimap, user multimap, iterable side input, multimap side input, channel/appendable, watermark handled upstream, custom user state) — typically a newly added or runner-specific StateKey variant.","commonSituations":"Runner and SDK harness version skew where the runner uses a newer StateKey proto field; experimental runner features sending unknown state key types.","solutions":["Upgrade the Beam SDK harness so its StateKey switch knows the reported key type.","Check the printed stateKey in the message and map it to the runner feature that produced it; disable that feature.","Ensure runner and SDK versions match and workers were restarted after upgrade.","File/consult a Beam issue if the key type is a standard one supported in newer releases."],"exampleFix":"// before: mixed versions (runner 2.60, harness 2.40 image)\n--sdk_harness_container_image=old-image\n// after\n--sdk_harness_container_image=gcr.io/.../beam_sdk_harness:<matching-runner-version>","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  // state access\n} catch (IllegalStateException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Unknown state key type\")) {\n    LOG.error(\"Runner sent unsupported StateKey {} — upgrade harness\", e.getMessage());\n  } else { throw e; }\n}","preventionTips":["Match runner and harness versions","Disable experimental state features on older harnesses","Restart workers after upgrades"],"tags":["state","cache","beam","version-mismatch"],"backgroundTag":"invalid-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}