apache/beam · error · CoderException

cannot encode a null Long

Error message

cannot encode a null Long

What it means

VarLongCoder encodes Java Longs as variable-length ints and, like VarIntCoder, rejects nulls at encode time because the varint format cannot represent null. Throwing CoderException here surfaces the problem at the point of serialization instead of producing corrupt bytes.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/VarLongCoder.java:50

 * always take 10 bytes, so {@link BigEndianLongCoder} may be preferable for longs that are known to
 * often be large or negative.
 */
public class VarLongCoder extends StructuredCoder<Long> {
  public static VarLongCoder of() {
    return INSTANCE;
  }

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

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

  private VarLongCoder() {}

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

  @Override
  public Long decode(InputStream inStream) throws IOException, CoderException {
    try {
      return VarInt.decodeLong(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 List<? extends Coder<?>> getCoderArguments() {
    return Collections.emptyList();

View on GitHub (pinned to 12126d8942)

Solutions

1. Replace null Longs with defaults (e.g. 0L) or filter them before encoding.
2. Wrap the coder: NullableCoder.of(VarLongCoder.of()).
3. Check upstream parsing/mapping logic that converts strings/records to Long and produces nulls.

Example fix

// before
VarLongCoder.of().encode(maybeNullLong, outStream);
// after
Coder<Long> coder = NullableCoder.of(VarLongCoder.of());
coder.encode(maybeNullLong, outStream); // handles null

if (value == null) { value = 0L; }
coder.encode(value, outStream);

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

try { coder.encode(v, out); } catch (CoderException e) { throw new IOException("null Long at encode", e); }

When it happens

Trigger: Calling VarLongCoder.of().encode(null, outStream), or a PCollection<Long>/state value/timer timestamp field being null when this coder serializes it.

Common situations: Null Long values from missing data fields (e.g. absent counts, unmapped joins), DoFn emitting null Longs, user code buffering null values into Beam state or side inputs.

Related errors

• cannot encode a null Integer
• cannot encode a null String
• cannot encode a null Integer
• cannot encode a null ValueKind
• Could not decode the default value with the provided coder %

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