apache/beam · error · ValueError

DoFn.StateParam expected StateSpec object.

Error message

DoFn.StateParam expected StateSpec object.

What it means

ValueError raised by `_StateDoFnParam.__init__` (exposed as `DoFn.StateParam`) when the `state_spec` argument is not an instance of `StateSpec`. State parameters must be declared with specs such as `CombiningValueStateSpec` or `ReadModifyWriteStateSpec`.

Solutions

  1. Pass a `StateSpec` instance, e.g. `DoFn.StateParam(CombiningValueStateSpec('running_sum', ...))` or `ReadModifyWriteStateSpec('cell', ...)`.
  2. Check the argument isn't a plain string name — specs carry the name internally.
  3. Ensure you imported the spec classes from `apache_beam.transforms.userstate`.

Example fix

// before
MY_STATE = DoFn.StateParam('counter')
// after
MY_STATE = DoFn.StateParam(ReadModifyWriteStateSpec('counter', default_value=0))
Defensive patterns

Strategy: type-guard

Validate before calling

from apache_beam.transforms.userstate import StateSpec
if not isinstance(state_spec, StateSpec):
    raise TypeError('expected StateSpec instance, got %r' % (state_spec,))

Type guard

from apache_beam.transforms.userstate import StateSpec
def is_state_spec(x) -> bool:
    return isinstance(x, StateSpec)

Try / catch

try:
    param = DoFn.StateParam(spec)
except ValueError as e:
    if 'StateSpec' in str(e):
        spec = ReadModifyWriteStateSpec(spec, default_value=0) if isinstance(spec, str) else None

Prevention

When it happens

Trigger: Writing `DoFn.StateParam('my_state')`, `DoFn.StateParam(some_string)`, or passing a raw name/spec-like object instead of a `StateSpec` instance when declaring a stateful DoFn parameter.

Common situations: Passing the state name string instead of a spec object; reusing timer specs for state; copying boilerplate and forgetting to wrap the state in a spec.

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

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

Appendix: source

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

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."""
  def __init__(self, timer_spec):
    # type: (TimerSpec) -> None
    if not isinstance(timer_spec, TimerSpec):
      raise ValueError("DoFn.TimerParam expected TimerSpec object.")
    self.timer_spec = timer_spec
    self.param_id = 'TimerParam(%s)' % timer_spec.name


class _BundleFinalizerParam(_DoFnParam):
  """Bundle Finalization DoFn parameter."""
  def __init__(self):
    self._callbacks = []

View on GitHub (pinned to 12126d8942)