apache/beam · error · IllegalArgumentException

{errorContext}: unable to decode {encodedValue}, encoding of

Error message

{errorContext}: unable to decode {encodedValue}, encoding of value {value}, using {coder}

What it means

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.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/SerializableUtils.java:167

   * deserialized.
   */
  public static <T> T ensureSerializableByCoder(Coder<T> coder, T value, String errorContext) {
    byte[] encodedValue;
    try {
      encodedValue = encodeToByteArray(coder, value);
    } catch (CoderException exn) {
      // TODO: Put in better element printing:
      // truncate if too long.
      throw new IllegalArgumentException(
          errorContext + ": unable to encode value " + value + " using " + coder, exn);
    }
    try {
      return decodeFromByteArray(coder, encodedValue);
    } catch (CoderException exn) {
      // TODO: Put in better encoded byte array printing:
      // use printable chars with escapes instead of codes, and
      // truncate if too long.
      throw new IllegalArgumentException(
          errorContext
              + ": unable to decode "
              + Arrays.toString(encodedValue)
              + ", encoding of value "
              + value
              + ", using "
              + coder,
          exn);
    }
  }

  private static final class ContextualObjectInputStream extends ObjectInputStream {
    private ContextualObjectInputStream(final InputStream in) throws IOException {
      super(in);
    }

    @Override
    protected Class<?> resolveClass(final ObjectStreamClass classDesc)

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify the Coder matches the runtime type of the value (e.g. StringUtf8Coder.of() for String, not another coder).
2. If using a custom Coder, test that decode(encode(value)) equals value for representative values, including edge cases.
3. Ensure required coders are registered / type parameters supplied, especially with generic or lambda-based transforms.
4. Inspect the printed encoded byte array and value in the message to identify where the encoding diverges.

Example fix

// before
Coder<MyType> coder = StringUtf8Coder.of();
SerializableUtils.ensureSerializableByCoder(coder, myValue, "checking");
// after
Coder<MyType> coder = MyTypeCoder.of(); // coder matching the value's actual type
SerializableUtils.ensureSerializableByCoder(coder, myValue, "checking");

if (!coder.getTypeDescriptor().getType().equals(value.getClass())) {
  throw new IllegalArgumentException("coder " + coder + " does not match value type " + value.getClass());
}

try {
  SerializableUtils.ensureSerializableByCoder(coder, value, ctx);
} catch (IllegalArgumentException e) {
  // log value type and coder, fall back to coder registry lookup
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• cannot encode a null String
• cannot encode a null Integer
• cannot encode a null ValueKind
• cannot encode a null Integer
• cannot encode a null Long

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/9cbc1aca4827c3a6. Report an issue: GitHub.