apache/beam · error · ValueError

DoFn.process() method-only parameter %s cannot be used in %s

Error message

DoFn.process() method-only parameter %s cannot be used in %s.

What it means

_validate_bundle_method ensures DoFnProcessParams (process-only special parameters like SideInputParam, StateParam, TimerParam, etc.) are not used on non-process methods (start_bundle/finish_bundle/bundle methods). Using them there is meaningless, so ValueError names the offending parameter and method.

Source

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

        raise NotImplementedError(
            f"DoFn {self.do_fn!r} has unsupported per-key DoFn param {d}. "
            "Per-key DoFn params are not yet supported for process_batch "
            "(https://github.com/apache/beam/issues/21653).")

      # Fallback to catch anything not explicitly supported
      if not d in (core.DoFn.WindowParam,
                   core.DoFn.TimestampParam,
                   core.DoFn.PaneInfoParam):
        raise ValueError(
            f"DoFn {self.do_fn!r} has unsupported process_batch "
            f"method parameter {d}")

  def _validate_bundle_method(self, method_wrapper):
    """Validate that none of the DoFnParameters are used in the function
    """
    for param in core.DoFn.DoFnProcessParams:
      if param in method_wrapper.defaults:
        raise ValueError(
            'DoFn.process() method-only parameter %s cannot be used in %s.' %
            (param, method_wrapper))

  def _validate_stateful_dofn(self):
    # type: () -> None
    userstate.validate_stateful_dofn(self.do_fn)

  def is_splittable_dofn(self):
    # type: () -> bool
    return self.get_restriction_provider() is not None

  def get_restriction_coder(self):
    # type: () -> Optional[TupleCoder]

    """Get coder for a restriction when processing an SDF. """
    if self.is_splittable_dofn():
      return TupleCoder([
          (self.get_restriction_provider().restriction_coder()),

View on GitHub (pinned to 12126d8942)

Solutions

1. Remove the process-only parameter from the bundle method
2. Access state via self.state_handler / explicit APIs if the DoFn is stateful, per Beam's documented patterns
3. Move logic needing those parameters into process()

Example fix

// before
def finish_bundle(self, si=DoFn.SideInputParam): ...
// after
def finish_bundle(self): ...

from apache_beam.transforms.core import DoFn
for m in ('start_bundle', 'finish_bundle'):
    d = getattr(MyDoFn, m, None)
    if d:
        assert not any(p in (d.__defaults__ or []) for p in DoFn.DoFnProcessParams), m

When it happens

Trigger: def finish_bundle(self, si=DoFn.SideInputParam) or adding DoFnProcessParams defaults to start_bundle/finish_bundle; validation via _validate at DoFnSignature creation.

Common situations: Copy-pasting the process() signature into finish_bundle; assuming start_bundle can access side inputs or state like process does.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• 'obj_to_invoke' has to be either a 'DoFn' or a 'RestrictionP
• Returning a %s from a ParDo or FlatMap is not allowed. Pleas
• ParDo must be called with a DoFn instance.
• Returning elements from _SubprocessDoFn.finish_bundle not sa
• assign_context.window should not be None. This might be due

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