apache/beam · error · ValueError

DoFn.RestrictionParam expected RestrictionProvider object.

Error message

DoFn.RestrictionParam expected RestrictionProvider object.

What it means

ValueError raised by `_RestrictionDoFnParam.__init__` (exposed as `DoFn.RestrictionParam`) when the supplied restriction_provider is not `None` and is not an instance of `RestrictionProvider`. Only a real restriction provider (or None) is accepted.

Solutions

1. Pass an object whose class subclasses `RestrictionProvider` (e.g. `OffsetRangeTracker`-based provider or a DoFn's `restriction_provider` implementation).
2. Pass `None` only if intentionally omitting the restriction.
3. Verify you didn't pass the provider's class rather than an instance.

Example fix

// before
param = DoFn.RestrictionParam(MyRestrictionProviderClass)
// after
param = DoFn.RestrictionParam(MyRestrictionProvider())  # instance of RestrictionProvider

from apache_beam.transforms.core import RestrictionProvider
if restriction_provider is not None and not isinstance(restriction_provider, RestrictionProvider):
    raise TypeError('expected RestrictionProvider instance')

from apache_beam.transforms.core import RestrictionProvider
def is_restriction_provider(x) -> bool:
    return x is None or isinstance(x, RestrictionProvider)

try:
    param = DoFn.RestrictionParam(provider)
except ValueError as e:
    if 'RestrictionProvider' in str(e):
        provider = provider() if isinstance(provider, type) else None

When it happens

Trigger: Writing `DoFn.RestrictionParam(MyDoFn)` or `DoFn.RestrictionParam(some_spec)` passing a DoFn, spec, class, or string instead of an object implementing `RestrictionProvider` (e.g. a `RangeTracker`-backed provider like those in `apache_beam.io.range_trackers` used with custom splittable DoFns).

Common situations: Confusing RestrictionParam with StateParam/TimerParam arguments; passing the provider class instead of an instance; custom splittable-DoFn boilerplate mistakes.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• DoFn.StateParam expected StateSpec object.
• DoFn.TimerParam expected TimerSpec object.
• DoFn.WatermarkEstimatorParam…
• RecordId unsupported in
• RecordOffset unsupported in

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/core.py:464

  def __eq__(self, other):
    if type(self) == type(other):
      return self.param_id == other.param_id
    return False

  def __hash__(self):
    return hash(self.param_id)

  def __repr__(self):
    return self.param_id


class _RestrictionDoFnParam(_DoFnParam):
  """Restriction Provider DoFn parameter."""
  def __init__(self, restriction_provider=None):
    # type: (typing.Optional[RestrictionProvider]) -> None
    if (restriction_provider is not None and
        not isinstance(restriction_provider, RestrictionProvider)):
      raise ValueError(
          'DoFn.RestrictionParam expected RestrictionProvider object.')
    self.restriction_provider = restriction_provider
    self.param_id = (
        'RestrictionParam(%s)' % restriction_provider.__class__.__name__)


class _StateDoFnParam(_DoFnParam):
  """State DoFn parameter."""
  def __init__(self, state_spec):
    # type: (StateSpec) -> None
    if not isinstance(state_spec, StateSpec):
      raise ValueError("DoFn.StateParam expected StateSpec object.")
    self.state_spec = state_spec
    self.param_id = 'StateParam(%s)' % state_spec.name


class _TimerDoFnParam(_DoFnParam):
  """Timer DoFn parameter."""

View on GitHub (pinned to 12126d8942)