apache/beam · error · IllegalArgumentException

Iterator at position " + i + " was null.

Error message

Iterator at position " + i + " was null.

What it means

PrefetchableIterators.concat validates every varargs iterator is non-null before chaining them. A null element would fail during iteration with an NPE, so concat fails immediately with this IllegalArgumentException stating the position of the null iterator.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/fn/stream/PrefetchableIterators.java:199

    };
  }

  /**
   * Concatentates the {@link Iterator}s.
   *
   * <p>{@link Iterable}s are first converted into a {@link PrefetchableIterable} via {@link
   * #maybePrefetchable}.
   *
   * <p>The returned {@link PrefetchableIterable} ensures that iterators which are returned
   * guarantee that {@link PrefetchableIterator#isReady} always advances till it finds an {@link
   * Iterable} that is not {@link PrefetchableIterator#isReady}. {@link
   * PrefetchableIterator#prefetch} is also guaranteed to advance past empty iterators till it finds
   * one that is not ready.
   */
  public static <T> PrefetchableIterator<T> concat(Iterator<T>... iterators) {
    for (int i = 0; i < iterators.length; ++i) {
      if (iterators[i] == null) {
        throw new IllegalArgumentException("Iterator at position " + i + " was null.");
      }
    }
    if (iterators.length == 0) {
      return emptyIterator();
    } else if (iterators.length == 1) {
      return maybePrefetchable(iterators[0]);
    }
    return concatIterators(Arrays.asList(iterators).iterator());
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Filter out null iterators before calling concat
2. Replace null iterators with Collections.emptyIterator()
3. Fix the source producing the null iterator to return an empty iterator instead
4. Null-check each iterator before composing

Example fix

// before
Iterator<T> it = PrefetchableIterators.concat(it1, null, it2);
// after
Iterator<T> it = PrefetchableIterators.concat(
    it1,
    maybeNull != null ? maybeNull : java.util.Collections.<T>emptyIterator(),
    it2);

for (int i = 0; i < iterators.length; i++) {
  java.util.Objects.requireNonNull(iterators[i], "iterator at " + i);
}

static <T> Iterator<T> orEmpty(Iterator<T> it) {
  return it != null ? it : java.util.Collections.<T>emptyIterator();
}

try {
  return PrefetchableIterators.concat(iterators);
} catch (IllegalArgumentException e) {
  return PrefetchableIterators.emptyIterator();
}

When it happens

Trigger: Calling PrefetchableIterators.concat(iteratorA, null) or passing an iterator array containing null elements.

Common situations: Collecting iterators from conditional branches where a branch produced null; building a collection of iterators from optional lookups that returned null.

Related errors

• Iterable at position ${i} was null.
• cannot encode a null Integer
• cannot encode a null Long
• cannot encode a null Short
• cannot encode a null BitSet

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