apache/beam · error · UnsupportedOperationException

Not expected to access DoFn.StartBundleContext from @Process

Error message

Not expected to access DoFn.StartBundleContext from @ProcessElement

What it means

DoFnTester emulates @ProcessElement execution, in which the StartBundleContext is not available; if user code inside @ProcessElement requests DoFn.StartBundleContext via a context parameter, the tester's context provider throws UnsupportedOperationException. Start bundle context is only valid within @StartBundle methods.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/DoFnTester.java:287

            @Override
            public CausedByDrain causedByDrain(DoFn<InputT, OutputT> doFn) {
              return processContext.causedByDrain();
            }

            @Override
            public PaneInfo paneInfo(DoFn<InputT, OutputT> doFn) {
              return processContext.pane();
            }

            @Override
            public PipelineOptions pipelineOptions() {
              return getPipelineOptions();
            }

            @Override
            public DoFn<InputT, OutputT>.StartBundleContext startBundleContext(
                DoFn<InputT, OutputT> doFn) {
              throw new UnsupportedOperationException(
                  "Not expected to access DoFn.StartBundleContext from @ProcessElement");
            }

            @Override
            public DoFn<InputT, OutputT>.FinishBundleContext finishBundleContext(
                DoFn<InputT, OutputT> doFn) {
              throw new UnsupportedOperationException(
                  "Not expected to access DoFn.FinishBundleContext from @ProcessElement");
            }

            @Override
            public DoFn<InputT, OutputT>.ProcessContext processContext(DoFn<InputT, OutputT> doFn) {
              return processContext;
            }

            @Override
            public InputT element(DoFn<InputT, OutputT> doFn) {
              return processContext.element();

View on GitHub (pinned to 12126d8942)

Solutions

1. Remove the StartBundleContext parameter from @ProcessElement; move bundle-level state access into @StartBundle/@FinishBundle
2. Access pipeline options via ProcessContext instead if that's the underlying need
3. Test with TestPipeline (running the real runner) instead of DoFnTester if context semantics must be exercised

Example fix

// before
@ProcessElement public void processElement(ProcessContext c, StartBundleContext sbc) {...}
// after
@StartBundle public void startBundle(StartBundleContext sbc) {...}
@ProcessElement public void processElement(ProcessContext c) {...}

// Only inject StartBundleContext in @StartBundle methods
boolean inStartBundle = method.isAnnotationPresent(StartBundle.class);

try {
  tester.processElement();
} catch (UnsupportedOperationException e) {
  // context requested in @ProcessElement; refactor DoFn
}

When it happens

Trigger: A DoFn whose @ProcessElement method declares a DoFn.StartBundleContext parameter, run under DoFnTester (test with .processElement(...) invoked).

Common situations: Reusing a DoFn that accesses bundle lifecycle contexts in processElement, then unit testing with the legacy DoFnTester.

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

• Not expected to access DoFn.FinishBundleContext from @Proces
• Cannot access key as parameter outside of @OnTimer method.
• Cannot access timerId as parameter outside of @OnTimer metho
• Not expected to access TimeDomain from @ProcessElement
• Not expected to access Restriction from a regular DoFn in Do

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