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.

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
• cannot encode a null Instant
• cannot encode a null KV
• IterableLikeCoder can not guarantee deterministic ordering.
• cannot encode a null BitSet

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

Appendix: 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)