{"record":{"id":"081aa324182e59b3","repo":"apache/beam","slug":"unsupported-timedomain-r","errorCode":null,"errorMessage":"Unsupported TimeDomain: %r.","messagePattern":"Unsupported TimeDomain: %r\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/userstate.py","lineNumber":202,"sourceCode":"        ('clear_bit', bool),\n        ('fire_timestamp', Optional['Timestamp']),\n        ('hold_timestamp', Optional['Timestamp']),\n        ('paneinfo', Optional['windowed_value.PaneInfo']),\n    ])\n\n\n# TODO(BEAM-9562): Plumb through actual key_coder and window_coder.\nclass TimerSpec(object):\n  \"\"\"Specification for a user stateful DoFn timer.\n     Read more about Timers here:\n     https://beam.apache.org/documentation/programming-guide/#timers\n  \"\"\"\n  prefix = \"ts-\"\n\n  def __init__(self, name: str, time_domain: str) -> None:\n    self.name = self.prefix + name\n    if time_domain not in (TimeDomain.WATERMARK, TimeDomain.REAL_TIME):\n      raise ValueError('Unsupported TimeDomain: %r.' % (time_domain, ))\n    self.time_domain = time_domain\n    self._attached_callback: Optional[Callable] = None\n\n  def __repr__(self) -> str:\n    return '%s(%s)' % (self.__class__.__name__, self.name)\n\n  def to_runner_api(\n      self, context: 'PipelineContext', key_coder: Coder,\n      window_coder: Coder) -> beam_runner_api_pb2.TimerFamilySpec:\n    return beam_runner_api_pb2.TimerFamilySpec(\n        time_domain=TimeDomain.to_runner_api(self.time_domain),\n        timer_family_coder_id=context.coders.get_id(\n            coders._TimerCoder(key_coder, window_coder)))\n\n\ndef on_timer(timer_spec: TimerSpec) -> Callable[[CallableT], CallableT]:\n  \"\"\"Decorator for timer firing DoFn method.\n","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/userstate.py#L184-L220","documentation":"TimerSpec.__init__ accepts only TimeDomain.WATERMARK or TimeDomain.REAL_TIME as the time_domain argument. Any other value (arbitrary strings, EVENT_TIME misspellings, processing-time variants) is rejected with a ValueError, since the runner needs a well-defined time domain to schedule the timer.","triggerScenarios":"TimerSpec('name', 'processing_time') with a wrong string; passing TimeDomain.EVENT_TIME or other enum members not in (WATERMARK, REAL_TIME); passing None or an int instead of a TimeDomain member.","commonSituations":"Typos like 'processingtime'; copy-pasting from other streaming frameworks that use different time-domain enums; assuming PROCESSING_TIME is a valid name when the Beam Python SDK calls it REAL_TIME.","solutions":["Use TimeDomain.WATERMARK for event-time timers or TimeDomain.REAL_TIME for processing-time timers","Import TimeDomain from apache_beam.transforms.userstate and use the enum members rather than raw strings","Fix misspellings — e.g. 'processing_time' should be TimeDomain.REAL_TIME"],"exampleFix":"// before\nspec = TimerSpec('my_timer', 'processing_time')\n// after\nfrom apache_beam.transforms.userstate import TimeDomain\nspec = TimerSpec('my_timer', TimeDomain.REAL_TIME)","handlingStrategy":"validation","validationCode":"from apache_beam.transforms.userstate import TimeDomain\nassert time_domain in (TimeDomain.WATERMARK, TimeDomain.REAL_TIME), f'bad time_domain: {time_domain!r}'","typeGuard":"def is_valid_time_domain(td) -> bool:\n    return td in (TimeDomain.WATERMARK, TimeDomain.REAL_TIME)","tryCatchPattern":"try:\n    spec = TimerSpec('t', time_domain)\nexcept ValueError as e:\n    raise ValueError(f'fix time_domain, must be TimeDomain.WATERMARK or REAL_TIME: {e}')","preventionTips":["Only use TimeDomain enum members, never raw strings","Remember Beam Python names: WATERMARK (event time) and REAL_TIME (processing time)","Construct TimerSpecs at module level so mistakes fail at import, not at pipeline run"],"tags":["python","apache-beam","timers","time-domain","invalid-value"],"backgroundTag":"invalid-enum-value","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"}