{"record":{"id":"9cbc1aca4827c3a6","repo":"apache/beam","slug":"errorcontext-unable-to-decode-encodedvalue-encoding-of-value","errorCode":null,"errorMessage":"{errorContext}: unable to decode {encodedValue}, encoding of value {value}, using {coder}","messagePattern":"(.+?): unable to decode (.+?), encoding of value (.+?), using (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/SerializableUtils.java","lineNumber":167,"sourceCode":"   * deserialized.\n   */\n  public static <T> T ensureSerializableByCoder(Coder<T> coder, T value, String errorContext) {\n    byte[] encodedValue;\n    try {\n      encodedValue = encodeToByteArray(coder, value);\n    } catch (CoderException exn) {\n      // TODO: Put in better element printing:\n      // truncate if too long.\n      throw new IllegalArgumentException(\n          errorContext + \": unable to encode value \" + value + \" using \" + coder, exn);\n    }\n    try {\n      return decodeFromByteArray(coder, encodedValue);\n    } catch (CoderException exn) {\n      // TODO: Put in better encoded byte array printing:\n      // use printable chars with escapes instead of codes, and\n      // truncate if too long.\n      throw new IllegalArgumentException(\n          errorContext\n              + \": unable to decode \"\n              + Arrays.toString(encodedValue)\n              + \", encoding of value \"\n              + value\n              + \", using \"\n              + coder,\n          exn);\n    }\n  }\n\n  private static final class ContextualObjectInputStream extends ObjectInputStream {\n    private ContextualObjectInputStream(final InputStream in) throws IOException {\n      super(in);\n    }\n\n    @Override\n    protected Class<?> resolveClass(final ObjectStreamClass classDesc)","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/SerializableUtils.java#L149-L185","documentation":"SerializableUtils.ensureSerializableByCoder encodes a value with the supplied Coder and then decodes it back; when decodeFromByteArray throws a CoderException it wraps it in this IllegalArgumentException. It means the produced byte array was not decodable by the given coder for that value — the encode/decode round-trip failed, typically because the value is not actually encodable by that coder (e.g. an unencodable element type) or the coder is inconsistent.","triggerScenarios":"Calling ensureSerializableByCoder(coder, value, errorContext) where coder.encode(value) succeeds but coder.decode(...) fails: mismatched coder/value pairing, a coder that cannot round-trip the value (e.g. coders requiring type registration or a TypeDescriptor that doesn't match the runtime value), or a broken custom Coder whose decode is stricter than its encode.","commonSituations":"Pipeline construction validation in Apache Beam: passing a coder for the wrong type (e.g. StringUtf8Coder for an Integer), custom coders with buggy encode/decode symmetry, or coders that lack required type arguments/registration after upgrading Beam versions.","solutions":["Verify the Coder matches the runtime type of the value (e.g. StringUtf8Coder.of() for String, not another coder).","If using a custom Coder, test that decode(encode(value)) equals value for representative values, including edge cases.","Ensure required coders are registered / type parameters supplied, especially with generic or lambda-based transforms.","Inspect the printed encoded byte array and value in the message to identify where the encoding diverges."],"exampleFix":"// before\nCoder<MyType> coder = StringUtf8Coder.of();\nSerializableUtils.ensureSerializableByCoder(coder, myValue, \"checking\");\n// after\nCoder<MyType> coder = MyTypeCoder.of(); // coder matching the value's actual type\nSerializableUtils.ensureSerializableByCoder(coder, myValue, \"checking\");","handlingStrategy":"validation","validationCode":"if (!coder.getTypeDescriptor().getType().equals(value.getClass())) {\n  throw new IllegalArgumentException(\"coder \" + coder + \" does not match value type \" + value.getClass());\n}","typeGuard":null,"tryCatchPattern":"try {\n  SerializableUtils.ensureSerializableByCoder(coder, value, ctx);\n} catch (IllegalArgumentException e) {\n  // log value type and coder, fall back to coder registry lookup\n}","preventionTips":["Always obtain coders from the CoderRegistry or via pipeline.getCoderRegistry().getCoder(TypeDescriptor.of(type)).","Unit-test custom coders for encode/decode round-trip equality.","Check coder type descriptors against element types when wiring transforms."],"tags":["beam","coder","serialization","round-trip"],"backgroundTag":"schema-validation-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}