apache/beam · error · CoderException

cannot encode a null Map

Error message

cannot encode a null Map

What it means

MapCoder's encode() refuses to encode a null Map. Beam coders encode values into a byte stream for serialization between pipeline stages; a null has no wire representation here, so the coder throws CoderException early rather than emitting a corrupt stream. Use NullableCoder to wrap the MapCoder if nulls must round-trip.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/MapCoder.java:74

  private Coder<K> keyCoder;
  private Coder<V> valueCoder;

  private MapCoder(Coder<K> keyCoder, Coder<V> valueCoder) {
    this.keyCoder = keyCoder;
    this.valueCoder = valueCoder;
  }

  @Override
  public void encode(Map<K, V> map, OutputStream outStream) throws IOException, CoderException {
    encode(map, outStream, Context.NESTED);
  }

  @Override
  public void encode(Map<K, V> map, OutputStream outStream, Context context)
      throws IOException, CoderException {
    if (map == null) {
      throw new CoderException("cannot encode a null Map");
    }

    int size = map.size();
    BitConverters.writeBigEndianInt(size, outStream);
    if (size == 0) {
      return;
    }

    // Since we handled size == 0 above, entry is guaranteed to exist before and after loop
    Iterator<Entry<K, V>> iterator = map.entrySet().iterator();
    Entry<K, V> entry = iterator.next();
    while (iterator.hasNext()) {
      keyCoder.encode(entry.getKey(), outStream);
      valueCoder.encode(entry.getValue(), outStream);
      entry = iterator.next();
    }

    keyCoder.encode(entry.getKey(), outStream);

View on GitHub (pinned to 12126d8942)

Solutions

1. Never emit null maps; replace them with Collections.emptyMap() before encoding
2. Wrap the coder with NullableCoder.of(mapCoder) so nulls are encoded as a flag byte
3. Guard in the DoFn: emit an empty map or skip the element when the map is null

Example fix

// before
out.add(null);
// after
out.add(record.getMap() == null ? Collections.emptyMap() : record.getMap());

if (map == null) { map = Collections.emptyMap(); } // or throw a clear app-level error

boolean isEncodable(java.util.Map<?,?> m) { return m != null; }

try { coder.encode(map, out, Context.OUTER); } catch (CoderException e) { /* handle null or encoding failure */ }

When it happens

Trigger: Calling MapCoder.of(kCoder, vCoder).encode(null, out, Context.OUTER), directly or via a pipeline element whose output is a null Map.

Common situations: PCollection of Map<K,V> where a DoFn emits null for missing data; deserialized records with absent maps; schema/Java bean fields defaulted to null.

Related errors

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

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