{"record":{"id":"08831200371cc5cc","repo":"apache/beam","slug":"failed-to-encode-key-s-for-side-input-id-s","errorCode":null,"errorMessage":"Failed to encode key %s for side input id %s.","messagePattern":"Failed to encode key (.+?) for side input id (.+?)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/MultimapSideInput.java","lineNumber":180,"sourceCode":"                    .setTransformId(\n                        keysRequest.getStateKey().getMultimapKeysSideInput().getTransformId())\n                    .setSideInputId(\n                        keysRequest.getStateKey().getMultimapKeysSideInput().getSideInputId())\n                    .setWindow(keysRequest.getStateKey().getMultimapKeysSideInput().getWindow())\n                    .setKey(encodedKey))\n            .build();\n\n    StateRequest request = keysRequest.toBuilder().setStateKey(stateKey).build();\n    return StateFetchingIterators.readAllAndDecodeStartingFrom(\n        Caches.subCache(cache, \"ValuesForKey\", encodedKey), beamFnStateClient, request, valueCoder);\n  }\n\n  private ByteString encodeKey(K k) {\n    ByteStringOutputStream output = new ByteStringOutputStream();\n    try {\n      keyCoder.encode(k, output);\n    } catch (IOException e) {\n      throw new IllegalStateException(\n          String.format(\n              \"Failed to encode key %s for side input id %s.\",\n              k, keysRequest.getStateKey().getMultimapKeysSideInput().getSideInputId()),\n          e);\n    }\n    return output.toByteString();\n  }\n}\n","sourceCodeStart":162,"sourceCodeEnd":189,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/MultimapSideInput.java#L162-L189","documentation":"MultimapSideInput.encodeKey serializes a side-input map key with the key Coder before querying the runner for the key set. If the coder's encode() throws IOException (or the output stream fails), it wraps the failure in an IllegalStateException reporting the key and the side input id. This means the key is not encodable with the declared coder.","triggerScenarios":"Reading a multimap side input via get(k) (or encodedKey) where k cannot be encoded by the key Coder — e.g. coder mismatch, null key, or a coder whose encode assumes non-null/valid values.","commonSituations":"Side input built with a different key coder than the one used at read time after pipeline edits; null keys; custom coders throwing on certain values; serialization of mutated/invalid objects.","solutions":["Verify the key Coder matches the actual key type and that keys are non-null and encodable.","Check for null keys before reading the side input and skip or default them.","Re-derive the side input so its coder registry matches the read site (same PCollectionView/tag).","Fix or replace custom Coders that throw on valid runtime values."],"exampleFix":"// before\nV v = sideInput.get(maybeNullKey);\n// after\nV v = maybeNullKey == null ? defaultValue : sideInput.get(maybeNullKey);","handlingStrategy":"validation","validationCode":"if (k == null || !keyCoder.getType().isInstance(k)) {\n  throw new IllegalArgumentException(\"Key not encodable for side input: \" + k);\n}","typeGuard":"boolean encodableKey(K k, Coder<K> coder) {\n  return k != null && coder.getType().isInstance(k);\n}","tryCatchPattern":"try {\n  V v = multimapSideInput.get(key);\n} catch (IllegalStateException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to encode key\")) {\n    LOG.error(\"Bad side input key {}: {}\", key, e.getMessage());\n  } else { throw e; }\n}","preventionTips":["Keep side input key coders consistent across pipeline edits","Reject null keys before reading side inputs","Test custom coders on all runtime key values"],"tags":["side-input","encoding","coder","beam"],"backgroundTag":"json-marshal-failed","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"}