{"record":{"id":"0fc344b9e4d14f1a","repo":"apache/beam","slug":"dofn-r-has-multiple-statespecs-with-the-same-name-s","errorCode":null,"errorMessage":"DoFn %r has multiple StateSpecs with the same name: %s.","messagePattern":"DoFn %r has multiple StateSpecs with the same name: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/userstate.py","lineNumber":302,"sourceCode":"\n\ndef is_stateful_dofn(dofn: 'DoFn') -> bool:\n  \"\"\"Determines whether a given DoFn is a stateful DoFn.\"\"\"\n\n  # A Stateful DoFn is a DoFn that uses user state or timers.\n  all_state_specs, all_timer_specs = get_dofn_specs(dofn)\n  return bool(all_state_specs or all_timer_specs)\n\n\ndef validate_stateful_dofn(dofn: 'DoFn') -> None:\n  \"\"\"Validates the proper specification of a stateful DoFn.\"\"\"\n\n  # Get state and timer specs.\n  all_state_specs, all_timer_specs = get_dofn_specs(dofn)\n\n  # Reject DoFns that have multiple state or timer specs with the same name.\n  if len(all_state_specs) != len(set(s.name for s in all_state_specs)):\n    raise ValueError(\n        'DoFn %r has multiple StateSpecs with the same name: %s.' %\n        (dofn, all_state_specs))\n  if len(all_timer_specs) != len(set(s.name for s in all_timer_specs)):\n    raise ValueError(\n        'DoFn %r has multiple TimerSpecs with the same name: %s.' %\n        (dofn, all_timer_specs))\n\n  # Reject DoFns that use timer specs without corresponding timer callbacks.\n  for timer_spec in all_timer_specs:\n    if not timer_spec._attached_callback:\n      raise ValueError((\n          'DoFn %r has a TimerSpec without an associated on_timer '\n          'callback: %s.') % (dofn, timer_spec))\n    method_name = timer_spec._attached_callback.__name__\n    if (timer_spec._attached_callback != getattr(dofn, method_name,\n                                                 None).__func__):  # type: ignore[union-attr]\n      raise ValueError((\n          'The on_timer callback for %s is not the specified .%s method '","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/userstate.py#L284-L320","documentation":"Apache Beam raises this ValueError during stateful DoFn validation when two or more StateSpecs on a DoFn share the same name. State specs are keyed by name, so duplicates would make state access ambiguous. validate_stateful_dofn detects the duplicate by comparing the spec count against the set of unique names before the pipeline runs.","triggerScenarios":"A DoFn class defines two class-level StateSpec attributes with the same name string, e.g. two ReadStateSpec('my_state') entries (or the same name reused across state types). validate_stateful_dofn is invoked during pipeline construction/execution and len(all_state_specs) != len(set(names)).","commonSituations":"Copy-pasting a state spec and forgetting to rename it; refactoring where two specs accidentally converge to one name; merging branches of a DoFn that each declared a state with the same string name.","solutions":["Rename one of the duplicate StateSpecs so every state name on the DoFn is unique.","If the duplicate is leftover dead code, delete the unused StateSpec attribute.","Check all specs via apache_beam.transforms.userstate.get_dofn_specs(dofn) to list names before re-running."],"exampleFix":"// before\nclass CountingDoFn(DoFn):\n  COUNTER_SPEC = ReadStateSpec('cells')\n  HISTORY_SPEC = ReadStateSpec('cells')  # duplicate name\n// after\nclass CountingDoFn(DoFn):\n  COUNTER_SPEC = ReadStateSpec('cells')\n  HISTORY_SPEC = ReadStateSpec('history')","handlingStrategy":"validation","validationCode":"from apache_beam.transforms.userstate import get_dofn_specs\nnames = [s.name for s in get_dofn_specs(MyDoFn)[0]]\nassert len(names) == len(set(names)), f'duplicate state names: {names}'","typeGuard":null,"tryCatchPattern":"try:\n  validate_stateful_dofn(MyDoFn)\nexcept ValueError as e:\n  if 'multiple StateSpecs with the same name' in str(e):\n    fix_duplicate_state_names(MyDoFn)\n  else:\n    raise","preventionTips":["Give each StateSpec a distinct, descriptive name string.","After refactoring a DoFn, run validate_stateful_dofn in a unit test.","Grep the DoFn class for repeated StateSpec('name') literals before committing."],"tags":["python","apache-beam","stateful-dofn","duplicate-name","validation"],"backgroundTag":"invalid-identifier-format","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"}