apache/beam · error · TypeError

Must provide context when not using SimpleInvoker

Error message

Must provide context when not using SimpleInvoker

What it means

DoFnInvoker.create_invoker selects SimpleInvoker when no per-window invocation features (side inputs, special params, stateful DoFn) are needed; otherwise it builds PerWindowInvoker, which requires a context object. A TypeError is raised if context is None in that case.

Solutions

Pass a DoFnContext instance (e.g. a simple DoFnContext / RunnerContext) as the context argument
If the DoFn truly needs no special params, use SimpleInvoker by ensuring signature has no defaults/state
Update custom runner code to construct a context as apache_beam.runners.common expects

Example fix

// before
DoFnInvoker.create_invoker(sig, output_handler)  # sig uses side inputs
// after
DoFnInvoker.create_invoker(sig, output_handler, context=DoFnContext(self))

Defensive patterns

Strategy: type-guard

Validate before calling

assert context is not None, 'PerWindowInvoker requires a DoFnContext'

Try / catch

try:
    invoker = DoFnInvoker.create_invoker(sig, handler, context=None)
except TypeError as e:
    invoker = DoFnInvoker.create_invoker(sig, handler, context=DoFnContext(None))

Prevention

Always supply a context when invoking DoFns with special params or side inputs
Prefer SimpleInvoker paths only for trivial DoFns

When it happens

Trigger: create_invoker(output_handler, signature, ...) with a signature needing PerWindowInvoker (defaults present or stateful DoFn) but context=None, e.g. custom runner or test harness invoking a side-input-consuming DoFn.

Common situations: Hand-rolled runners/tests calling create_invoker without a DoFnContext; frameworks wiring DoFn invocation that regress on context plumbing.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/runners/common.py:537

                      before invoking the process method.
        process_invocation: If True, this function may return an invoker that
                            performs extra optimizations for invoking process()
                            method efficiently.
        user_state_context: The UserStateContext instance for the current
                            Stateful DoFn.
        bundle_finalizer_param: The param that passed to a process method, which
                                allows a callback to be registered.
    """
    side_inputs = side_inputs or []
    use_per_window_invoker = process_invocation and (
        side_inputs or input_args or input_kwargs or
        signature.process_method.defaults or
        signature.process_batch_method.defaults or signature.is_stateful_dofn())
    if not use_per_window_invoker:
      return SimpleInvoker(output_handler, signature)
    else:
      if context is None:
        raise TypeError("Must provide context when not using SimpleInvoker")
      return PerWindowInvoker(
          output_handler,
          signature,
          context,
          side_inputs,
          input_args,
          input_kwargs,
          user_state_context,
          bundle_finalizer_param)

  def invoke_process(
      self,
      windowed_value,  # type: WindowedValue
      restriction=None,
      watermark_estimator_state=None,
      additional_args=None,
      additional_kwargs=None):
    # type: (...) -> Iterable[SplitResultResidual]

View on GitHub (pinned to 12126d8942)