apache/beam · error · IllegalArgumentException

Iterable at position ${i} was null.

Error message

Iterable at position ${i} was null.

What it means

PrefetchableIterables.concat validates that every varargs iterable is non-null before composing them into one PrefetchableIterable. A null element would cause a NullPointerException later during iteration, so the library fails fast with this IllegalArgumentException identifying the offending position.

Source

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

      return (PrefetchableIterable<T>) iterable;
    }
    return new Default<T>() {
      @Override
      public PrefetchableIterator<T> createIterator() {
        return PrefetchableIterators.maybePrefetchable(iterable.iterator());
      }
    };
  }

  /**
   * Concatentates the {@link Iterable}s.
   *
   * <p>See {@link PrefetchableIterators#concat} for additional details.
   */
  public static <T> PrefetchableIterable<T> concat(Iterable<T>... iterables) {
    for (int i = 0; i < iterables.length; ++i) {
      if (iterables[i] == null) {
        throw new IllegalArgumentException("Iterable at position " + i + " was null.");
      }
    }
    if (iterables.length == 0) {
      return emptyIterable();
    } else if (iterables.length == 1) {
      return maybePrefetchable(iterables[0]);
    }
    return new Default<T>() {
      @SuppressWarnings("methodref.receiver")
      @Override
      public PrefetchableIterator<T> createIterator() {
        return PrefetchableIterators.concatIterators(
            FluentIterable.from(iterables).transform(Iterable::iterator).iterator());
      }
    };
  }

  /** Limits the {@link PrefetchableIterable} to the specified number of elements. */

View on GitHub (pinned to 12126d8942)

Solutions

1. Filter null entries from the array/collection before concatenating
2. Substitute an empty iterable for absent sources
3. Fix the upstream producer so it returns an empty iterable instead of null
4. When all inputs may be missing, call concat() with no args (returns emptyIterable)

Example fix

// before
PrefetchableIterable<T> it = PrefetchableIterables.concat(a, maybeNull, b);
// after
PrefetchableIterable<T> it = PrefetchableIterables.concat(
    a,
    maybeNull != null ? maybeNull : PrefetchableIterables.<T>emptyIterable(),
    b);

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

static <T> Iterable<T> orEmpty(Iterable<T> it) {
  return it != null ? it : PrefetchableIterables.<T>emptyIterable();
}

try {
  return PrefetchableIterables.concat(iterables);
} catch (IllegalArgumentException e) {
  return PrefetchableIterables.emptyIterable();
}

When it happens

Trigger: Calling PrefetchableIterables.concat(iterableA, null, iterableB) or passing an array of iterables where any element is null.

Common situations: Building a combined iterable from optional sources where some sources were absent (map lookup or cache miss returned null); refactoring from Arrays.asList which tolerated nulls until iteration.

Related errors

• Iterator 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/a316226c79d2c501. Report an issue: GitHub.