apache/beam · error · IllegalArgumentException

cannot call getPipelineOptions() in a null context

Error message

cannot call getPipelineOptions() in a null context

What it means

StateContexts.NULL_CONTEXT is a placeholder StateContext used when no real context is bound (e.g. state accessed outside a pipeline execution context). Calling getPipelineOptions() on it always throws this IllegalArgumentException — it is a deliberate sentinel guard, and the faulty input is the context-less call site, not any argument.

Solutions

1. Move the getPipelineOptions() call to where a real StateContext exists (inside a DoFn's @Setup/@ProcessElement with state).
2. Pass the pipeline options through explicitly (e.g. via a constructor or side input) instead of reading them from a null context.
3. Check that state is being accessed through StateContexts.withCancellation/combined contexts rather than the bare NULL_CONTEXT.

When it happens

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

Appendix: source

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

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.beam.sdk.state;

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

View on GitHub (pinned to 12126d8942)