{"record":{"id":"58efa6852f0fb755","repo":"apache/beam","slug":"the-timestamp-of-deter-remainder-should-be-a-duration-or-a","errorCode":null,"errorMessage":"The timestamp of deter_remainder() should be a Duration or a Timestamp, or None.","messagePattern":"The timestamp of deter_remainder\\(\\) should be a Duration or a Timestamp, or None\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/sdf_utils.py","lineNumber":99,"sourceCode":"\n    Self-checkpoint could happen during processing elements. When executing an\n    DoFn.process(), you may want to stop processing an element and resuming\n    later if current element has been processed quit a long time or you also\n    want to have some outputs from other elements. ``defer_remainder()`` can be\n    called on per element if needed.\n\n    Args:\n      deferred_time: A relative ``Duration`` that indicates the ideal time gap\n        between now and resuming, or an absolute ``Timestamp`` for resuming\n        execution time. If the time_delay is None, the deferred work will be\n        executed as soon as possible.\n    \"\"\"\n\n    # Record current time for calculating deferred_time later.\n    with self._lock:\n      self._timestamp = Timestamp.now()\n      if deferred_time and not isinstance(deferred_time, (Duration, Timestamp)):\n        raise ValueError(\n            'The timestamp of deter_remainder() should be a '\n            'Duration or a Timestamp, or None.')\n      self._deferred_timestamp = deferred_time\n      checkpoint = self.try_split(0)\n      if checkpoint:\n        _, self._deferred_residual = checkpoint\n\n  def check_done(self):\n    with self._lock:\n      return self._restriction_tracker.check_done()\n\n  def current_progress(self) -> 'RestrictionProgress':\n    with self._lock:\n      return self._restriction_tracker.current_progress()\n\n  def try_split(self, fraction_of_remainder):\n    with self._lock:\n      return self._restriction_tracker.try_split(fraction_of_remainder)","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/sdf_utils.py#L81-L117","documentation":"ThreadsafeRestrictionTracker.defer_remainder() accepts an optional deferred_time used to report how long the remainder is deferred. If a truthy value is passed that is neither a Duration nor a Timestamp, this ValueError is raised before checkpointing the remainder.","triggerScenarios":"Calling tracker.defer_remainder(x) where x is truthy but of an unexpected type — e.g. an int, float, datetime.timedelta, or string — instead of apache_beam.utils.timestamp.Duration or Timestamp (or None/0/falsy).","commonSituations":"Passing datetime.timedelta or seconds-as-number from user code that schedules deferral; confusing Duration vs Timestamp units when wiring a custom splittable DoFn.","solutions":["Convert the value to apache_beam.utils.timestamp.Duration (or Timestamp) before calling defer_remainder","Pass None to defer without an explicit deferred time","Use Timestamp.of()/Duration(seconds=...) helpers for correct types"],"exampleFix":"// before\ntracker.defer_remainder(30)\n// after\nfrom apache_beam.utils.timestamp import Duration\ntracker.defer_remainder(Duration(seconds=30))","handlingStrategy":"type-guard","validationCode":"from apache_beam.utils.timestamp import Duration, Timestamp\nassert deferred_time is None or isinstance(deferred_time, (Duration, Timestamp))","typeGuard":"from apache_beam.utils.timestamp import Duration, Timestamp\ndef is_deferred_time(x) -> bool:\n    return x is None or isinstance(x, (Duration, Timestamp))","tryCatchPattern":"try:\n    tracker.defer_remainder(dt)\nexcept ValueError as e:\n    if 'Duration or a Timestamp' in str(e):\n        tracker.defer_remainder(None)\n    else:\n        raise","preventionTips":["Use Duration(seconds=...) / Timestamp helpers, never raw ints or timedelta","Type-annotate deferral parameters","Cover defer_remainder calls in unit tests"],"tags":["apache-beam","sdf","type-mismatch","timestamp"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}