apache/beam · error · IllegalArgumentException

cannot call sideInput() in a null context

Error message

cannot call sideInput() in a null context

What it means

The NULL_CONTEXT StateContext in StateContexts throws unconditionally from sideInput(PCollectionView): side inputs can only be resolved against a live pipeline execution window, and this context exists only to satisfy the interface when no context is available. The faulty input is a side-input lookup attempted outside real pipeline execution.

Solutions

1. Access side inputs inside a DoFn's process element method where the ProcessContext supplies a real window.
2. If you need the view's data outside execution, materialize it via a runner-supported mechanism (e.g. pass as pipeline option or a side input to a transform) rather than calling sideInput() directly.
3. Ensure you are not unit-testing context objects created via StateContexts.nullContext(); construct a real context instead.

When it happens

Trigger: Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/state/StateContexts.java:37 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/state/StateContexts.java:37

import org.apache.beam.sdk.annotations.Internal;
import org.apache.beam.sdk.options.PipelineOptions;
import org.apache.beam.sdk.transforms.windowing.BoundedWindow;
import org.apache.beam.sdk.values.PCollectionView;

/** <b><i>For internal use only; no backwards-compatibility guarantees.</i></b> */
@Internal
public class StateContexts {
  private static final StateContext<BoundedWindow> NULL_CONTEXT =
      new StateContext<BoundedWindow>() {
        @Override
        public PipelineOptions getPipelineOptions() {
          throw new IllegalArgumentException("cannot call getPipelineOptions() in a null context");
        }

        @Override
        public <T> T sideInput(PCollectionView<T> view) {
          throw new IllegalArgumentException("cannot call sideInput() in a null context");
        }

        @Override
        public BoundedWindow window() {
          throw new IllegalArgumentException("cannot call window() in a null context");
        }
      };

  /** Returns a fake {@link StateContext}. */
  @SuppressWarnings("unchecked")
  public static <W extends BoundedWindow> StateContext<W> nullContext() {
    return (StateContext<W>) NULL_CONTEXT;
  }

  public static <W extends BoundedWindow> StateContext<W> windowOnlyContext(W window) {
    return new WindowOnlyContext<>(window);
  }

View on GitHub (pinned to 12126d8942)