apache/beam · error · IllegalArgumentException

cannot call getPipelineOptions() in a null context

Error message

cannot call getPipelineOptions() in a null context

What it means

CombineContextFactory.nullContext() returns a placeholder Combine.Context for tests whose getPipelineOptions() always throws IllegalArgumentException. Calling getPipelineOptions() on the null context is by definition unsupported: a null context represents 'no side inputs and no pipeline options available'.

Source

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

 * limitations under the License.
 */
package org.apache.beam.sdk.util;

import org.apache.beam.sdk.annotations.Internal;
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() {

View on GitHub (pinned to 12126d8942)

Solutions

1. Test with a real Context that returns your PipelineOptions instead of nullContext()
2. Refactor the CombineFn to not require PipelineOptions when operating in the null context (guard with feature checks)
3. Create a minimal anonymous Context implementation returning a TestPipelineOptions or a stub PipelineOptions in tests
4. Verify CombineFnUtil.bindContext was not given a null context in production wiring

Example fix

// before
Context ctx = CombineContextFactory.nullContext(); // throws on getPipelineOptions()
combineFn.addInput(ctx, acc, value);
// after
Context ctx = new Context() {
  public PipelineOptions getPipelineOptions() { return testOptions; }
  public <T> T sideInput(PCollectionView<T> v) { throw new UnsupportedOperationException(); }
};
combineFn.addInput(ctx, acc, value);

Context ctx = CombineContextFactory.nullContext();
// guard in CombineFn:
if (useNullContext) { /* skip pipeline-options-dependent logic */ }

try {
  PipelineOptions opts = context.getPipelineOptions();
} catch (IllegalArgumentException e) {
  // null context: operate without pipeline options or fail fast with a clear message
}

When it happens

Trigger: Calling context.getPipelineOptions() on the Context returned by CombineContextFactory.nullContext(), typically inside a custom CombineFn's addInput/mergeAccumulators/extractOutput when running in a test or a pipeline that supplied the null context.

Common situations: Unit-testing a CombineFn that reads PipelineOptions (e.g. custom config) using nullContext(); production code paths accidentally wired with nullContext via CombineFnUtil.bindContext with a null context.

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 sideInput() in a null context
• Cannot serialize the CombineFn resulting from CombineFnUtil.
• Could not obtain a Coder for the accumulator
• Failed to convert PipelineOptions to JSON
• A list of URNs for overriding transforms was provided but th

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