apache/beam · error · IllegalArgumentException

cannot call sideInput() in a null context

Error message

cannot call sideInput() in a null context

What it means

The null Combine.Context placeholder also rejects sideInput(view) with this IllegalArgumentException, because a null context carries no side inputs. Any attempt to read a side input while combining under the null context fails immediately.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/CombineContextFactory.java:39

import org.apache.beam.sdk.options.PipelineOptions;
import org.apache.beam.sdk.state.StateContext;
import org.apache.beam.sdk.transforms.CombineWithContext.Context;
import org.apache.beam.sdk.values.PCollectionView;

/** Factory that produces {@code Combine.Context} based on different inputs. */
@Internal
public class CombineContextFactory {

  private static final Context NULL_CONTEXT =
      new Context() {
        @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");
        }
      };

  /** Returns a fake {@code Combine.Context} for tests. */
  public static Context nullContext() {
    return NULL_CONTEXT;
  }

  /** Returns a {@code Combine.Context} that wraps a {@link StateContext}. */
  public static Context createFromStateContext(final StateContext<?> c) {
    return new Context() {
      @Override
      public PipelineOptions getPipelineOptions() {
        return c.getPipelineOptions();
      }

      @Override
      public <T> T sideInput(PCollectionView<T> view) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a real Context whose sideInput returns test fixtures when testing side-input-aware CombineFns
2. Split the CombineFn so side-input logic is not exercised in null-context paths, or guard sideInput calls on availability
3. Wire the pipeline so the combine step is bound to a context containing the required side inputs (e.g. via CombineFnUtil.bindContext with a non-null context)

Example fix

// before
Context ctx = CombineContextFactory.nullContext();
T side = ctx.sideInput(view); // throws
// after
Context ctx = new Context() {
  public PipelineOptions getPipelineOptions() { throw new UnsupportedOperationException(); }
  public <T> T sideInput(PCollectionView<T> v) { return testSideInputs.get(v); }
};
T side = ctx.sideInput(view);

if (requiresSideInputs) {
  // do not use nullContext()
  Context ctx = makeContextWithSideInputs(testViews);
}

try {
  T side = context.sideInput(view);
} catch (IllegalArgumentException e) {
  // bound with null context: side inputs are unavailable here
}

When it happens

Trigger: Calling context.sideInput(someView) inside a CombineFn (addInput, mergeAccumulators, extractOutput, or accessor) when the Combine operation was configured with CombineContextFactory.nullContext().

Common situations: CombineFn logic that reads side inputs being unit-tested with nullContext(); a pipeline using Combine.globally/PerKey with contexts bound to null while the combine function expects side inputs.

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

• cannot call getPipelineOptions() in a null context
• Cannot serialize the CombineFn resulting from CombineFnUtil.
• Could not obtain a Coder for the accumulator
• Illegal access to pipeline after visitor traversal was compl
• Pipeline update will not be possible because the following t

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