apache/beam · error · IllegalArgumentException

cannot call window() in a null context

Error message

cannot call window() in a null context

What it means

window() on StateContexts.NULL_CONTEXT always throws: the current BoundedWindow is only meaningful while processing an element, and this null context is a stand-in used when state is touched with no execution context bound. The faulty input is the call site invoking window() outside element processing.

Solutions

1. Call window() from within @ProcessElement/@OnTimer where the context carries the current window.
2. Pass the window in explicitly to helper code instead of reading it from a context object that may be null.
3. Avoid capturing a StateContext before execution begins; obtain it from the DoFn's context parameters.

When it happens

Trigger: Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/state/StateContexts.java:42 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/915dc97c32f903b6. Report an issue: GitHub.

Appendix: source

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

/** <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);
  }

  private static class WindowOnlyContext<W extends BoundedWindow> implements StateContext<W> {
    private final W window;

    private WindowOnlyContext(W window) {
      this.window = window;

View on GitHub (pinned to 12126d8942)