apache/beam · error · CoderException

cannot encode a null Long

Error message

cannot encode a null Long

What it means

BigEndianLongCoder.encode() rejects null Long values with a CoderException because Beam coders encode values, not nulls, unless the coder is wrapped in NullableCoder. The message mirrors the Integer coder's null check.

Source

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

/** A {@link BigEndianLongCoder} encodes {@link Long Longs} in 8 bytes, big-endian. */
public class BigEndianLongCoder extends AtomicCoder<Long> {

  public static BigEndianLongCoder of() {
    return INSTANCE;
  }

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

  private static final BigEndianLongCoder INSTANCE = new BigEndianLongCoder();
  private static final TypeDescriptor<Long> TYPE_DESCRIPTOR = new TypeDescriptor<Long>() {};

  private BigEndianLongCoder() {}

  @Override
  public void encode(Long value, OutputStream outStream) throws IOException, CoderException {
    if (value == null) {
      throw new CoderException("cannot encode a null Long");
    }
    BitConverters.writeBigEndianLong(value, outStream);
  }

  @Override
  public Long decode(InputStream inStream) throws IOException, CoderException {
    try {
      return BitConverters.readBigEndianLong(inStream);
    } catch (EOFException | UTFDataFormatException exn) {
      // These exceptions correspond to decoding problems, so change
      // what kind of exception they're branded as.
      throw new CoderException(exn);
    }
  }

  @Override
  public void verifyDeterministic() {}

View on GitHub (pinned to 12126d8942)

Solutions

1. Filter nulls: .apply(Filter.by(Objects::nonNull)).
2. Use NullableCoder.of(BigEndianLongCoder.of()) via setCoder() on the PCollection.
3. Map null to a domain sentinel (e.g. -1L or 0L) before output.
4. In direct encode() calls, add a null check before invoking encode.

Example fix

// before
out.output(value == null ? null : Long.parseLong(value));
// after
Long v = value == null ? null : Long.parseLong(value);
if (v != null) { out.output(v); }

if (value == null) { throw new IllegalArgumentException("Long element is null; filter before encoding"); }

boolean isEncodable(Long v) { return v != null; }

try {
  coder.encode(value, out);
} catch (CoderException e) {
  LOG.error("Null Long element", e);
  throw e;
}

When it happens

Trigger: Encoding a null Long directly via BigEndianLongCoder.of().encode(null, out), or a PCollection<Long> containing nulls flowing through a serialization step.

Common situations: Map/DoFn outputting null Longs (e.g. failed conversions returning null), aggregations producing null, code migrated from Optional<Long> where null slipped through.

Related errors

• cannot encode a null Integer
• cannot encode a null Short
• cannot encode a null BitSet
• cannot encode a null byte[]
• cannot encode a null value

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