{"record":{"id":"5aad814d16fa4e3e","repo":"apache/beam","slug":"cannot-call-getpipelineoptions-in-a-window-only-context","errorCode":null,"errorMessage":"cannot call getPipelineOptions() in a window-only context","messagePattern":"cannot call getPipelineOptions\\(\\) in a window-only context","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/state/StateContexts.java","lineNumber":66,"sourceCode":"  public static <W extends BoundedWindow> StateContext<W> nullContext() {\n    return (StateContext<W>) NULL_CONTEXT;\n  }\n\n  public static <W extends BoundedWindow> StateContext<W> windowOnlyContext(W window) {\n    return new WindowOnlyContext<>(window);\n  }\n\n  private static class WindowOnlyContext<W extends BoundedWindow> implements StateContext<W> {\n    private final W window;\n\n    private WindowOnlyContext(W window) {\n      this.window = window;\n    }\n\n    @Override\n    public PipelineOptions getPipelineOptions() {\n      throw new IllegalArgumentException(\n          \"cannot call getPipelineOptions() in a window-only context\");\n    }\n\n    @Override\n    public <T> T sideInput(PCollectionView<T> view) {\n      throw new IllegalArgumentException(\"cannot call sideInput() in a window-only context\");\n    }\n\n    @Override\n    public W window() {\n      return window;\n    }\n  }\n}\n","sourceCodeStart":48,"sourceCodeEnd":80,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/state/StateContexts.java#L48-L80","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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().","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().","Guard the call with a null/check or wrap in try-catch for IllegalArgumentException and supply a fallback value."],"exampleFix":"// before\nPipelineOptions options = ctx.getPipelineOptions();\n\n// after\n// in setup(ProcessContext context)\nthis.options = context.getPipelineOptions();","handlingStrategy":"try-catch","validationCode":"// Ensure the context is not window-only before calling\n// Avoid entirely: read PipelineOptions in setup(ProcessContext ctx) instead of state callbacks","typeGuard":"boolean isWindowOnlyContext = false; // no public type; treat all StateContexts as window-only for getPipelineOptions()","tryCatchPattern":"try {\n  options = stateContext.getPipelineOptions();\n} catch (IllegalArgumentException e) {\n  options = fallbackOptions; // captured in setup()\n}","preventionTips":["Read PipelineOptions only in setup()/startBundle() from ProcessContext, never in state or timer callbacks","Treat stateContext.getPipelineOptions() as unsupported; pass needed values as fields or side inputs","Do not build test harnesses on StateContexts.windowOnly() if the code under test reads pipeline options"],"tags":["apache-beam","state-api","illegal-argument"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}