apache/beam · error · CoderException

CoderException(exn)

Error message

CoderException(exn)

What it means

ByteCoder.decode catches EOFException and UTFDataFormatException and re-throws them wrapped in CoderException. The visible message is that of the wrapped exception; Beam re-brands these failures so callers can distinguish decode problems from other IO errors.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/ByteCoder.java:61

    if (value == null) {
      throw new CoderException("cannot encode a null Byte");
    }
    outStream.write(value);
  }

  @Override
  public Byte decode(InputStream inStream) throws IOException, CoderException {
    try {
      // value will be between 0-255, -1 for EOF
      int value = inStream.read();
      if (value == -1) {
        throw new EOFException("EOF encountered decoding 1 byte from input stream");
      }
      return (byte) value;
    } catch (EOFException | UTFDataFormatException exn) {
      // These exceptions correspond to decoding problems, so change
      // what kind of exception they're branded as.
      throw new CoderException(exn);
    }
  }

  /**
   * {@inheritDoc}
   *
   * <p>{@link ByteCoder} will never throw a {@link Coder.NonDeterministicException}; bytes can
   * always be encoded deterministically.
   */
  @Override
  public void verifyDeterministic() {}

  /**
   * {@inheritDoc}
   *
   * @return {@code true}. This coder is injective.
   */
  @Override

View on GitHub (pinned to 12126d8942)

Solutions

1. Catch CoderException at the call site and handle as a data-corruption case
2. Verify the encoder used to write the stream matches ByteCoder
3. Re-align stream offsets so decode starts exactly at an encoded Byte
4. Regenerate corrupted input

Example fix

// before
Byte b = coder.decode(in); // CoderException propagates and kills the DoFn
// after
try {
  Byte b = coder.decode(in);
} catch (CoderException e) {
  LOG.error("Malformed byte element: " + e.getCause(), e);
  corruptElements.inc();
}

try { ... } catch (CoderException e) { Throwable cause = e.getCause(); /* EOFException or UTFDataFormatException: corrupt/truncated input */ }

When it happens

Trigger: Decoding a Byte when the stream is at EOF or the underlying read raises UTFDataFormatException (malformed stream contents), i.e. corrupt or truncated single-byte elements.

Common situations: Misaligned stream reads, decoding data written by a different coder, truncated serialized data shipped between workers, tests feeding wrong fixture bytes.

Related errors

• invalid length " + length
• EOF encountered decoding 1 byte from input stream
• Expected a %s with components but received %s
• Error decoding payload
• Illegal access to pipeline after visitor traversal was compl

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