{"record":{"id":"c932f38b389c77d1","repo":"apache/beam","slug":"dofn-stateparam-expected-statespec-object","errorCode":null,"errorMessage":"DoFn.StateParam expected StateSpec object.","messagePattern":"DoFn\\.StateParam expected StateSpec object\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/core.py","lineNumber":476,"sourceCode":"class _RestrictionDoFnParam(_DoFnParam):\n  \"\"\"Restriction Provider DoFn parameter.\"\"\"\n  def __init__(self, restriction_provider=None):\n    # type: (typing.Optional[RestrictionProvider]) -> None\n    if (restriction_provider is not None and\n        not isinstance(restriction_provider, RestrictionProvider)):\n      raise ValueError(\n          'DoFn.RestrictionParam expected RestrictionProvider object.')\n    self.restriction_provider = restriction_provider\n    self.param_id = (\n        'RestrictionParam(%s)' % restriction_provider.__class__.__name__)\n\n\nclass _StateDoFnParam(_DoFnParam):\n  \"\"\"State DoFn parameter.\"\"\"\n  def __init__(self, state_spec):\n    # type: (StateSpec) -> None\n    if not isinstance(state_spec, StateSpec):\n      raise ValueError(\"DoFn.StateParam expected StateSpec object.\")\n    self.state_spec = state_spec\n    self.param_id = 'StateParam(%s)' % state_spec.name\n\n\nclass _TimerDoFnParam(_DoFnParam):\n  \"\"\"Timer DoFn parameter.\"\"\"\n  def __init__(self, timer_spec):\n    # type: (TimerSpec) -> None\n    if not isinstance(timer_spec, TimerSpec):\n      raise ValueError(\"DoFn.TimerParam expected TimerSpec object.\")\n    self.timer_spec = timer_spec\n    self.param_id = 'TimerParam(%s)' % timer_spec.name\n\n\nclass _BundleFinalizerParam(_DoFnParam):\n  \"\"\"Bundle Finalization DoFn parameter.\"\"\"\n  def __init__(self):\n    self._callbacks = []","sourceCodeStart":458,"sourceCodeEnd":494,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/core.py#L458-L494","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a `StateSpec` instance, e.g. `DoFn.StateParam(CombiningValueStateSpec('running_sum', ...))` or `ReadModifyWriteStateSpec('cell', ...)`.","Check the argument isn't a plain string name — specs carry the name internally.","Ensure you imported the spec classes from `apache_beam.transforms.userstate`."],"exampleFix":"// before\nMY_STATE = DoFn.StateParam('counter')\n// after\nMY_STATE = DoFn.StateParam(ReadModifyWriteStateSpec('counter', default_value=0))","handlingStrategy":"type-guard","validationCode":"from apache_beam.transforms.userstate import StateSpec\nif not isinstance(state_spec, StateSpec):\n    raise TypeError('expected StateSpec instance, got %r' % (state_spec,))","typeGuard":"from apache_beam.transforms.userstate import StateSpec\ndef is_state_spec(x) -> bool:\n    return isinstance(x, StateSpec)","tryCatchPattern":"try:\n    param = DoFn.StateParam(spec)\nexcept ValueError as e:\n    if 'StateSpec' in str(e):\n        spec = ReadModifyWriteStateSpec(spec, default_value=0) if isinstance(spec, str) else None","preventionTips":["Always declare state with CombiningValueStateSpec / ReadModifyWriteStateSpec / BagStateSpec","Never pass a bare string state name to StateParam","Keep state declarations as module-level constants wrapping real specs"],"tags":["apache-beam","dofn","state","type-check"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}