{"record":{"id":"e98f664dc7f43e05","repo":"apache/beam","slug":"errorcontext-unable-to-encode-value-value-using-coder","errorCode":null,"errorMessage":"{errorContext}: unable to encode value {value} using {coder}","messagePattern":"(.+?): unable to encode 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":158,"sourceCode":"            + \"implement serialization correctly.  Before: %s, after: %s\",\n        coder,\n        copy);\n\n    return copy;\n  }\n\n  /**\n   * Serializes an arbitrary T with the given {@code Coder<T>} and verifies that it can be correctly\n   * 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    }","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/SerializableUtils.java#L140-L176","documentation":"ensureSerializableByCoder round-trips a value through a Coder to verify it is encodable/decodable. A CoderException during encoding is rethrown as IllegalArgumentException '<errorContext>: unable to encode value <value> using <coder>'. It indicates the value does not conform to what the coder expects (e.g. nulls where the coder forbids them, or wrong element type).","triggerScenarios":"Calling ensureSerializableByCoder(context, value, coder) where encodeToByteArray throws CoderException — e.g. encoding null with a coder that rejects nulls, or an element that does not match the coder's declared type.","commonSituations":"Pipeline construction-time validation of DoFn inputs/outputs; feeding null or mismatched elements into PCollections whose coders were inferred for a different type; custom coders that fail on edge-case values.","solutions":["Fix the value so it matches the coder's contract (remove nulls, correct the element type).","Use a coder that supports the value (e.g. NullableCoder to permit nulls).","Verify the CoderRegistry/coder inference selected the right coder for the PCollection's element type.","If you own a custom coder, fix its encode() to handle the failing value or throw a clearer CoderException."],"exampleFix":"// before\nCoder<String> c = StringUtf8Coder.of();\nensureSerializableByCoder(\"check\", maybeNull, c); // throws on null\n// after\nCoder<String> c = NullableCoder.of(StringUtf8Coder.of());\nensureSerializableByCoder(\"check\", maybeNull, c);","handlingStrategy":"validation","validationCode":"if (value == null && !(coder instanceof NullableCoder)) { throw new IllegalArgumentException(\"coder does not support nulls\"); }","typeGuard":"static <T> boolean coderAccepts(Coder<T> c, T v) { return v != null || c instanceof NullableCoder; }","tryCatchPattern":"try { ensureSerializableByCoder(\"context\", value, coder); } catch (IllegalArgumentException e) { LOG.error(\"coder mismatch: {}\", e.getMessage()); throw e; }","preventionTips":["Verify PCollection coders match the actual element types.","Use NullableCoder for fields that may be null.","Add round-trip coder tests for custom coders covering edge cases."],"tags":["java","beam","coder","serialization","pipeline-validation"],"backgroundTag":"type-mismatch","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"}