apache/beam · error · CoderException

cannot encode a null Iterable

Error message

cannot encode a null Iterable

What it means

registerByteSizeObserver on IterableLikeCoder was called with a null iterable while estimating encoded sizes (e.g. for GroupByKey output size estimation). The coder cannot observe element sizes of an absent iterable, so the null IterableT argument is rejected; null must instead be represented by a NullableCoder wrapper.

Source

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

        this, "IterableLikeCoder can not guarantee deterministic ordering.");
  }

  /**
   * {@inheritDoc}
   *
   * @return {@code true} if the iterable is of a known class that supports lazy counting of byte
   *     size, since that requires minimal extra computation.
   */
  @Override
  public boolean isRegisterByteSizeObserverCheap(IterableT iterable) {
    return iterable instanceof ElementByteSizeObservableIterable;
  }

  @Override
  public void registerByteSizeObserver(IterableT iterable, ElementByteSizeObserver observer)
      throws Exception {
    if (iterable == null) {
      throw new CoderException("cannot encode a null Iterable");
    }

    if (iterable instanceof ElementByteSizeObservableIterable) {
      observer.setLazy();
      ElementByteSizeObservableIterable<?, ?> observableIterable =
          (ElementByteSizeObservableIterable<?, ?>) iterable;
      observableIterable.addObserver(
          new IteratorObserver(observer, iterable instanceof Collection));
    } else {
      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;
        observer.update(4L);
        for (T elem : collection) {
          elementCoder.registerByteSizeObserver(elem, observer);
        }
      } else {

View on GitHub (pinned to 12126d8942)

Solutions

1. Substitute Collections.emptyList() for null collections upstream.
2. Wrap with NullableCoder.of(...) so nulls have an encoded size.
3. Filter null collection elements before the size-observed stage.

Example fix

// before
coder.registerByteSizeObserver(null, observer); // CoderException
// after
coder.registerByteSizeObserver(items == null ? Collections.emptyList() : items, observer);

if (iterable != null) { coder.registerByteSizeObserver(iterable, observer); }

When it happens

Trigger: Calling coder.registerByteSizeObserver(null, observer) on a ListCoder/IterableCoder/SetCoder, or Beam's size estimation running over a PCollection whose iterable elements include nulls.

Common situations: Sized side inputs containing null collections; pipelines where list-valued fields are optional and unsanitized.

Related errors

• cannot encode a null {iterableName}
• cannot encode a null Instant
• IterableLikeCoder can not guarantee deterministic ordering.
• cannot encode a null KV
• cannot encode a null Integer

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