What causes "cannot encode a null {iterableName}" in apache/beam?

Replace null collections with Collections.emptyList() before encoding.

apache/beam · error · CoderException

cannot encode a null {iterableName}

Error message

cannot encode a null {iterableName}

What it means

IterableLikeCoder.encode() throws CoderException when the Iterable-like value passed is null. Beam coders have no null representation; the message names the concrete iterable type via iterableName (e.g. "cannot encode a null List").

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/IterableLikeCoder.java:103

  /////////////////////////////////////////////////////////////////////////////
  // Internal operations below here.

  private final Coder<T> elementCoder;
  private final String iterableName;

  protected IterableLikeCoder(Coder<T> elementCoder, String iterableName) {
    checkArgument(elementCoder != null, "element Coder for IterableLikeCoder must not be null");
    checkArgument(iterableName != null, "iterable name for IterableLikeCoder must not be null");
    this.elementCoder = elementCoder;
    this.iterableName = iterableName;
  }

  @Override
  public void encode(IterableT iterable, OutputStream outStream)
      throws IOException, CoderException {
    if (iterable == null) {
      throw new CoderException("cannot encode a null " + iterableName);
    }
    if (iterable instanceof Collection) {
      // We can know the size of the Iterable.  Use an encoding with a
      // leading size field, followed by that many elements.
      Collection<T> collection = (Collection<T>) iterable;
      BitConverters.writeBigEndianInt(collection.size(), outStream);
      for (T elem : collection) {
        elementCoder.encode(elem, outStream);
      }
    } else {
      // We don't know the size without traversing it so use a fixed size buffer
      // and encode as many elements as possible into it before outputting the size followed
      // by the elements.
      BitConverters.writeBigEndianInt(-1, outStream);
      BufferedElementCountingOutputStream countingOutputStream =
          new BufferedElementCountingOutputStream(outStream);
      for (T elem : iterable) {
        countingOutputStream.markElementStart();

View on GitHub (pinned to 12126d8942)

Solutions

Replace null collections with Collections.emptyList() before encoding.
Wrap with NullableCoder.of(...) if nulls must round-trip.
Filter out null collection elements upstream.

Example fix

// before
c.encode(null, out); // CoderException
// after
c.encode(myList == null ? Collections.emptyList() : myList, out);

Defensive patterns

Strategy: validation

Validate before calling

if (iterable != null) { coder.encode(iterable, out); }

Prevention

Substitute Collections.emptyList() for null collections before encoding.
Use NullableCoder.of(...) for genuinely optional collections.
Initialize collection fields to empty, never null, in pipeline element classes.

When it happens

Trigger: Encoding a null List/Iterable/Set through ListCoder, IterableCoder, SetCoder, etc., either directly or via a pipeline element that is null.

Common situations: DoFns that emit KV<K, List<V>> where a grouping produced no values and code passes null instead of an empty collection.

Related errors

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