What causes "cannot call sideInput() in a window-only context" in apache/beam?

Only access side inputs via the DoFn's process-context (@AlwaysFetchSideInputs / parameter access), not from state contexts.

apache/beam · error · IllegalArgumentException

cannot call sideInput() in a window-only context

Error message

cannot call sideInput() in a window-only context

What it means

The window-only StateContext returned by StateContexts.windowOnly() carries only a window and no pipeline graph, so sideInput(PCollectionView) cannot be resolved. Beam overrides sideInput() to throw IllegalArgumentException to prevent accessing side inputs where they are unavailable. Side inputs require a full evaluation context that a window-only context does not have.

Solutions

Only access side inputs via the DoFn's process-context (@AlwaysFetchSideInputs / parameter access), not from state contexts.
Pass the side input value into the state callback explicitly as a parameter captured during processElement.
Guard the call in try-catch for IllegalArgumentException and fall back to a default value.

Example fix

// before
T value = stateContext.sideInput(view);

// after
T value = this.capturedSideInput; // read in processElement via side input parameter

Defensive patterns

Strategy: validation

Validate before calling

// Only access side inputs through ProcessContext parameters in @ProcessElement methods,
// never via a StateContext obtained from StateContexts.windowOnly(...) or onTimer contexts

Type guard

if (stateContext instanceof StateContexts.WindowOnlyStateContext) {
  throw new IllegalStateException("sideInput() unsupported in window-only context");
}

Try / catch

try {
  value = stateContext.sideInput(view);
} catch (IllegalArgumentException e) {
  value = defaultValue;
}

Prevention

Fetch side inputs via DoFn process-element side-input parameters and pass values into state logic explicitly
Never call sideInput() from onTimer or readState callbacks
Keep side-input reads in one layer of the pipeline to avoid leaking them into state contexts

When it happens

Trigger: Calling sideInput(view) on a StateContext that was created as a window-only context, e.g. inside a state or timer callback resolved against StateContexts.windowOnly(window), or any code path where the view's data cannot be looked up.

Common situations: Attempting to read a PCollectionView from within an onTimer or state callback in a context that lacks the side-input map; refactored helper methods reused across contexts; tests constructing windowOnly contexts.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

    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;
    }

    @Override
    public PipelineOptions getPipelineOptions() {
      throw new IllegalArgumentException(
          "cannot call getPipelineOptions() in a window-only context");
    }

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

    @Override
    public W window() {
      return window;
    }
  }
}

View on GitHub (pinned to 12126d8942)