apache/beam · error · IllegalArgumentException

cannot call getPipelineOptions() in a window-only context

Error message

cannot call getPipelineOptions() in a window-only context

What it means

In Apache Beam, a state context can be 'window-only' (carrying only the window, e.g. when a DoFn is invoked in a context without full pipeline access). The window-only StateContext implementation overrides getPipelineOptions() to unconditionally throw IllegalArgumentException, because pipeline options are not available in that context. This is a deliberate guard against using API surface that is undefined here.

Solutions

1. Do not call getPipelineOptions() from state/timer callbacks; instead pass needed options as side inputs or capture them in the DoFn via setup()/startBundle() from ProcessContext.getPipelineOptions().
2. Ensure the context used at the call site is a full StateContext (bound to a real pipeline invocation), not a window-only one from StateContexts.windowOnly().
3. Guard the call with a null/check or wrap in try-catch for IllegalArgumentException and supply a fallback value.

Example fix

// before
PipelineOptions options = ctx.getPipelineOptions();

// after
// in setup(ProcessContext context)
this.options = context.getPipelineOptions();

// Ensure the context is not window-only before calling
// Avoid entirely: read PipelineOptions in setup(ProcessContext ctx) instead of state callbacks

boolean isWindowOnlyContext = false; // no public type; treat all StateContexts as window-only for getPipelineOptions()

try {
  options = stateContext.getPipelineOptions();
} catch (IllegalArgumentException e) {
  options = fallbackOptions; // captured in setup()
}

When it happens

Trigger: Calling stateContext.getPipelineOptions() from inside a DoFn/state callback whose context is a window-only context (created via StateContexts.windowOnly(...)), e.g. reading pipeline options from state requests or timers where only the window is known.

Common situations: A DoFn method annotated for state/timer access tries to read PipelineOptions to get job flags; code shared between a full ProcessContext-based path and a state-based path calls getPipelineOptions() unconditionally; unit tests using 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

• ApproximateUnique.PerKey needs an estimation error between…
• cannot call sideInput() in a window-only context
• Cannot create from non-Java
• Cannot read state-written iterable without state reader.
• error writing state

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

Appendix: source

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

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

    @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)