apache/beam · error · ValueError

'obj_to_invoke' has to be either a 'DoFn' or a 'RestrictionP

Error message

'obj_to_invoke' has to be either a 'DoFn' or a 'RestrictionProvider'. Received %r instead.

What it means

DoFnSignature.__init__ validates that obj_to_invoke is a DoFn, RestrictionProvider, or WatermarkEstimatorProvider before extracting method arguments. Anything else cannot provide a recognizable process method, so a ValueError is raised immediately.

Source

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


class MethodWrapper(object):
  """For internal use only; no backwards-compatibility guarantees.

  Represents a method that can be invoked by `DoFnInvoker`."""
  def __init__(self, obj_to_invoke, method_name):
    """
    Initiates a ``MethodWrapper``.

    Args:
      obj_to_invoke: the object that contains the method. Has to either be a
                    `DoFn` object or a `RestrictionProvider` object.
      method_name: name of the method as a string.
    """

    if not isinstance(obj_to_invoke,
                      (DoFn, RestrictionProvider, WatermarkEstimatorProvider)):
      raise ValueError(
          '\'obj_to_invoke\' has to be either a \'DoFn\' or '
          'a \'RestrictionProvider\'. Received %r instead.' % obj_to_invoke)

    self.args, self.defaults = core.get_function_arguments(obj_to_invoke,
                                                           method_name)
    # TODO(BEAM-5878) support kwonlyargs on Python 3.
    self.method_value = getattr(obj_to_invoke, method_name)
    self.method_name = method_name

    self.has_userstate_arguments = False
    self.state_args_to_replace = {}  # type: Dict[str, core.StateSpec]
    self.timer_args_to_replace = {}  # type: Dict[str, core.TimerSpec]
    self.timestamp_arg_name = None  # type: Optional[str]
    self.window_arg_name = None  # type: Optional[str]
    self.key_arg_name = None  # type: Optional[str]
    self.restriction_provider = None
    self.restriction_provider_arg_name = None
    self.watermark_estimator_provider = None

View on GitHub (pinned to 12126d8942)

Solutions

Pass an instance of apache_beam.transforms.core.DoFn (e.g. MyDoFn(), not MyDoFn)
If using splittable DoFn machinery, ensure the object exposes a RestrictionProvider
Check that a runner/plugin isn't forwarding a wrapped or partial object into DoFnSignature

Example fix

// before
sig = DoFnSignature(MyDoFn)  # class, not instance
// after
sig = DoFnSignature(MyDoFn())

Defensive patterns

Strategy: type-guard

Validate before calling

from apache_beam.transforms.core import DoFn
assert isinstance(obj, DoFn), f'expected DoFn instance, got {type(obj)}'

Type guard

def is_dofn_instance(obj): return isinstance(obj, DoFn)

Prevention

Instantiate DoFn classes before passing them
Don't pass plain functions where a DoFn is required

When it happens

Trigger: Constructing DoFnSignature(obj) directly, or invoking a DoFn via runner common.py where a plain function, class (not instance), callable object, or None was passed instead of a DoFn instance.

Common situations: Passing a top-level function where a DoFn is expected; forgetting to instantiate the DoFn class (DoFn vs MyDoFn()); custom runners or test harnesses building invokers with the wrong object.

Related errors

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