{"record":{"id":"6041e9af5e6876fe","repo":"apache/beam","slug":"timestamp-precision-must-be-between-0-and-d-inclusive-but","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":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/schemas.py","lineNumber":1037,"sourceCode":"  always in ``[0, 10**precision)``.\n  ``subseconds`` is an INT16 field for precision < 5 and an INT32\n  field otherwise.\n\n  Note: Timestamp originating from Python to xlang still defaults to\n  MicrosInstant for backwards compatibility. To override the mapping of\n  Timestamp to this logical type, re-register using\n  :func:`~LogicalType.register_logical_type(ParameterizedTimestamp)`.\n  \"\"\"\n  def __init__(self, precision: Optional[int] = None) -> None:\n    if precision is None:\n      # A timestamp:v1 proto without its precision argument is malformed;\n      # decoding at a guessed precision would silently misscale subseconds.\n      raise ValueError(\n          'beam:logical_type:timestamp:v1 requires a precision argument.')\n    # The argument arrives as np.int32 when decoded from a schema proto.\n    precision = int(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    self._precision = precision\n\n  @classmethod\n  def urn(cls):\n    return common_urns.timestamp.urn\n\n  def representation_type(self) -> type:  # type: ignore[override]\n    # Unlike other logical types, the representation depends on the\n    # argument, so this is an instance method rather than a classmethod.\n    if self._precision < _TIMESTAMP_SHORT_PRECISION_LIMIT:\n      return ParameterizedTimestampShortRepresentation\n    return ParameterizedTimestampRepresentation\n\n  @classmethod\n  def language_type(cls):\n    return Timestamp","sourceCodeStart":1019,"sourceCodeEnd":1055,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/schemas.py#L1019-L1055","documentation":"ParameterizedTimestamp validates its precision argument: after int coercion it must be between 0 and Timestamp.NANOS_PRECISION (9, nanosecond precision). Values outside that range raise ValueError. Precision denotes the number of subsecond digits the timestamp encodes.","triggerScenarios":"Calling ParameterizedTimestamp(precision=-1), precision=10, precision=100, or any non-None value that is not an integer in [0, 9]; passing a string/float that coerces out of range.","commonSituations":"Confusing precision (digit count, max 9) with a time unit enum or nanosecond magnitude (e.g. passing 1_000_000_000); off-by-one misuse thinking milliseconds are precision 3+something; passing fractional precision values.","solutions":["Use precision as a digit count between 0 (seconds) and 9 (nanoseconds): seconds=0, millis=3, micros=6, nanos=9.","Clamp or validate the precision before constructing: 0 <= int(precision) <= 9.","Convert a unit enum to a digit count before passing it in."],"exampleFix":"// before\nlt = ParameterizedTimestamp(precision=1_000_000_000)  # out of range\n\n// after\nlt = ParameterizedTimestamp(precision=9)  # nanosecond precision","handlingStrategy":"validation","validationCode":"def valid_precision(p):\n    return isinstance(p, (int, float)) and 0 <= int(p) <= 9","typeGuard":"def is_precision(p) -> bool:\n    return isinstance(p, int) and not isinstance(p, bool) and 0 <= p <= 9","tryCatchPattern":"try:\n    lt = ParameterizedTimestamp(precision=p)\nexcept ValueError:\n    p = min(max(int(p), 0), 9)\n    lt = ParameterizedTimestamp(precision=p)","preventionTips":["Remember precision is a digit count 0-9 (0=seconds, 3=millis, 6=micros, 9=nanos), not a magnitude.","Clamp user/config-supplied precision values before constructing.","Use named constants (MICROS=6) instead of raw numbers."],"tags":["python","apache-beam","timestamp","precision","range-check"],"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-14T16:17:12.679Z"}