{"record":{"id":"2fa24133b828f116","repo":"apache/beam","slug":"failed-to-encode-key-for-multimap-user-state-id-s","errorCode":null,"errorMessage":"Failed to encode key for multimap user state id %s.","messagePattern":"Failed to encode key for multimap user state id (.+?)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/MultimapUserState.java","lineNumber":521,"sourceCode":"      return output.toByteString();\n    } catch (IOException e) {\n      throw new IllegalStateException(\n          String.format(\n              \"Failed to encode values for multimap user state id %s.\",\n              keysStateRequest.getStateKey().getMultimapKeysUserState().getUserStateId()),\n          e);\n    }\n  }\n\n  private StateRequest createUserStateRequest(K key) {\n    try {\n      ByteStringOutputStream output = new ByteStringOutputStream();\n      mapKeyCoder.encode(key, output);\n      StateRequest.Builder request = userStateRequest.toBuilder();\n      request.getStateKeyBuilder().getMultimapUserStateBuilder().setMapKey(output.toByteString());\n      return request.build();\n    } catch (IOException e) {\n      throw new IllegalStateException(\n          String.format(\n              \"Failed to encode key for multimap user state id %s.\",\n              keysStateRequest.getStateKey().getMultimapKeysUserState().getUserStateId()),\n          e);\n    }\n  }\n\n  private CachingStateIterable<V> getPersistedValues(Object structuralKey, K key) {\n    return persistedValues\n        .computeIfAbsent(\n            structuralKey,\n            unused -> {\n              StateRequest request = createUserStateRequest(key);\n              return KV.of(\n                  key,\n                  StateFetchingIterators.readAllAndDecodeStartingFrom(\n                      Caches.subCache(\n                          cache,","sourceCodeStart":503,"sourceCodeEnd":539,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/MultimapUserState.java#L503-L539","documentation":"Beam Fn harness throws this IllegalStateException from createMultimapKeysUserState/createUserStateRequest when it fails to protobuf-encode the user's map key with the registered key coder while building a StateRequest for a multimap user state. Encoding an in-memory key should never fail, so an IOException here signals a broken/mismatched coder rather than a data problem. The original IOException is attached as the cause.","triggerScenarios":"The multimap state key coder's encode() throws IOException for the given key value while constructing the StateRequest that sets the map key on a multimap user state.","commonSituations":"A custom Coder whose encode() performs I/O or throws on certain values; pipeline deserialization producing a misconfigured coder; a coder registered for the state key that does not actually support the key type being written.","solutions":["Inspect the wrapped IOException cause to find which coder and value failed to encode","Verify the multimap state's key coder matches the actual key type written to the state","Fix the custom coder's encode() so it never throws IOException for valid key values","Check Beam SDK/harness version alignment between runner and SDK coders"],"exampleFix":"// before: custom coder throws on null elements\npublic void encode(String value, OutputStream out) {\n  if (value == null) throw new IOException(\"null key\");\n  ...\n}\n// after: handle all valid values deterministically\npublic void encode(String value, OutputStream out) throws IOException {\n  StringUtf8Coder.of().encode(value == null ? \"\" : value, out);\n}","handlingStrategy":"validation","validationCode":"// Ensure the key coder accepts the value before writing state\ntry (ByteArrayOutputStream unused = new ByteArrayOutputStream()) {\n  mapKeyCoder.verifyDeterministic(); // and ensure key is non-null\n} catch (CoderException | NonDeterministicException e) {\n  throw new IllegalArgumentException(\"key not encodable\", e);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use standard Beam coders for state keys","Never write null keys to multimap user state","Log the state id and key value when coder failures occur"],"tags":["java","apache-beam","state-api","coder-encoding"],"backgroundTag":"internal-invariant-violation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}