{"record":{"id":"054469416ce7ff91","repo":"apache/beam","slug":"timestamp-precision-must-be-between-0-and-d-inclusive-but-054469","errorCode":null,"errorMessage":"Timestamp precision must be between 0 and %d (inclusive), but was %d.","messagePattern":"Timestamp precision must be between 0 and (.+?) \\(inclusive\\), but was (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/utils/timestamp.py","lineNumber":93,"sourceCode":"  def __init__(\n      self,\n      seconds: Union[int, float] = 0,\n      subseconds: Union[int, float] = 0,\n      precision: int = MICROS_PRECISION,\n      *,\n      micros: Optional[Union[int, float]] = None) -> None:\n    if not isinstance(seconds, (int, float)):\n      raise TypeError(\n          'Cannot interpret %s %s as seconds.' % (seconds, type(seconds)))\n    if not isinstance(subseconds, (int, float)):\n      raise TypeError(\n          'Cannot interpret %s %s as subseconds.' %\n          (subseconds, type(subseconds)))\n    if not isinstance(precision, int):\n      raise TypeError(\n          'Cannot interpret %s %s as precision.' % (precision, type(precision)))\n    if not 0 <= precision <= Timestamp.NANOS_PRECISION:\n      raise ValueError(\n          'Timestamp precision must be between 0 and %d (inclusive), '\n          'but was %d.' % (Timestamp.NANOS_PRECISION, precision))\n    if micros is not None:\n      if not isinstance(micros, (int, float)):\n        raise TypeError(\n            'Cannot interpret %s %s as micros.' % (micros, type(micros)))\n      if subseconds:\n        raise ValueError(\n            'micros and subseconds are mutually exclusive, got micros=%s, '\n            'subseconds=%s.' % (micros, subseconds))\n      if precision != Timestamp.MICROS_PRECISION:\n        raise ValueError(\n            'micros implies microsecond precision (6) but precision was %d; '\n            'use subseconds instead.' % precision)\n      subseconds = micros\n    self._precision = precision\n    total = int(seconds * _POW_10[precision]) + int(subseconds)\n    self._seconds, self._subseconds = divmod(total, _POW_10[precision])","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/utils/timestamp.py#L75-L111","documentation":"Timestamp.__init__ restricts precision to the inclusive range 0 through Timestamp.NANOS_PRECISION (9). Precision above 9 (finer than nanoseconds) or negative is rejected with a ValueError since _POW_10 lookup and internal storage cannot represent it.","triggerScenarios":"Timestamp(seconds=1, precision=10) or precision=-1; from_rfc3339 with more than 9 fractional-second digits flows into precision=len(digits) checks (guarded separately at 4069 for strings, but direct calls hit this).","commonSituations":"Parsing timestamps with picosecond (12-digit) fractions from scientific data; off-by-one with len(digits) where a decimal separator was miscounted; negative precision from bad arithmetic.","solutions":["Use precision <= 9 (NANOS_PRECISION); truncate finer digits","Clamp: precision = max(0, min(precision, Timestamp.NANOS_PRECISION))","For sub-nanosecond data, pre-round the subseconds value instead of raising precision"],"exampleFix":"// before\nTimestamp(seconds=s, precision=len(digits))  # digits may be 12 long\n// after\nprecision = min(len(digits), Timestamp.NANOS_PRECISION)\nTimestamp(seconds=s, precision=precision)","handlingStrategy":"validation","validationCode":"if not 0 <= precision <= Timestamp.NANOS_PRECISION:\n    precision = max(0, min(precision, Timestamp.NANOS_PRECISION))","typeGuard":null,"tryCatchPattern":"try:\n    ts = Timestamp(seconds=s, precision=p)\nexcept ValueError as e:\n    log.warning('clamping precision: %s', e)\n    ts = Timestamp(seconds=s, precision=min(p, Timestamp.NANOS_PRECISION))","preventionTips":["Reference Timestamp.NANOS_PRECISION instead of hardcoding bounds","Truncate high-precision sources to 9 digits before constructing","Clamp parsed digit counts with min(len(digits), 9)"],"tags":["python","value-error","timestamp","range"],"backgroundTag":"value-out-of-range","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"}