apache/beam · error · CoderException

cannot encode a null Byte

Error message

cannot encode a null Byte

What it means

ByteCoder.encode throws CoderException when the Byte value to encode is null. Beam coders for boxed types reject nulls unless wrapped in NullableCoder, because the wire format has no representation for null.

Source

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

/** A {@link ByteCoder} encodes {@link Byte} values in 1 byte using Java serialization. */
public class ByteCoder extends AtomicCoder<Byte> {

  public static ByteCoder of() {
    return INSTANCE;
  }

  /////////////////////////////////////////////////////////////////////////////

  private static final ByteCoder INSTANCE = new ByteCoder();
  private static final TypeDescriptor<Byte> TYPE_DESCRIPTOR = new TypeDescriptor<Byte>() {};

  private ByteCoder() {}

  @Override
  public void encode(Byte value, OutputStream outStream) throws IOException, CoderException {
    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);
    }

View on GitHub (pinned to 12126d8942)

Solutions

1. Filter or default null values before they reach the coder: value == null ? (byte) 0 : value
2. Use NullableCoder.of(ByteCoder.of()) as the PCollection's coder when nulls are valid
3. Fix the upstream transform to skip null records
4. Model nullable data with a sentinel or Optional-like type instead of a bare Byte

Example fix

// before
out.output(row.getOptionalByte()); // may be null
// after
Byte b = row.getOptionalByte();
out.output(b == null ? (byte) 0 : b);
// or: .setCoder(NullableCoder.of(ByteCoder.of()))

if (value == null) throw new IllegalArgumentException("null Byte not supported by ByteCoder; filter or use NullableCoder");

static boolean isNonNullByte(Byte b) { return b != null; }

try { coder.encode(value, out); } catch (CoderException e) { /* null Byte: default or dead-letter */ }

When it happens

Trigger: Calling ByteCoder.of().encode(null, outStream), or a DoFn emitting null Byte values into a PCollection<Byte> coded with plain ByteCoder, or a sink serializing null Byte elements.

Common situations: Nullable map values, JSON/database rows with missing numeric columns mapped to null Byte, aggregation results that default to null, a schema change making a previously non-null column nullable.

Related errors

• cannot estimate size for unsupported null value
• cannot encode a null Double
• cannot encode a null ReadableDuration
• cannot encode a null Float
• cannot encode a null Map

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