{"record":{"id":"10e13eddff34d7af","repo":"apache/beam","slug":"invalid-subseconds-d-for-timestamp-with-precision-d","errorCode":null,"errorMessage":"Invalid subseconds %d for Timestamp with precision %d.","messagePattern":"Invalid subseconds (.+?) for Timestamp with precision (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/schemas.py","lineNumber":1068,"sourceCode":"      return ParameterizedTimestampShortRepresentation\n    return ParameterizedTimestampRepresentation\n\n  @classmethod\n  def language_type(cls):\n    return Timestamp\n\n  def to_representation_type(self, value: Timestamp):\n    # Verify that the value can be represented exactly at this type's precision\n    if value.precision() != self._precision:\n      value = value.to_precision(self._precision)\n    return self.representation_type()(value.seconds(), value.subseconds())\n\n  def to_language_type(self, value) -> Timestamp:\n    subseconds = int(value.subseconds)\n    # Match Java's toInputType: out-of-range subseconds indicate data\n    # corruption or a precision mismatch.\n    if not 0 <= subseconds < 10**self._precision:\n      raise ValueError(\n          'Invalid subseconds %d for Timestamp with precision %d.' %\n          (subseconds, self._precision))\n    return Timestamp(\n        seconds=int(value.seconds),\n        subseconds=subseconds,\n        precision=self._precision)\n\n  @classmethod\n  def argument_type(cls):\n    return np.int32\n\n  def argument(self):\n    return self._precision\n\n  @classmethod\n  def _from_typing(cls, typ):\n    # A bare Timestamp typehint has no precision; default to micros.\n    return cls(Timestamp.MICROS_PRECISION)","sourceCodeStart":1050,"sourceCodeEnd":1086,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/schemas.py#L1050-L1086","documentation":"ParameterizedTimestamp.to_language_type() converts a proto Timestamp value into a beam Timestamp, validating that subseconds fits within the instance's precision (0 <= subseconds < 10**precision). Out-of-range subseconds indicate data corruption or a precision mismatch (mirroring Java's toInputType) and raise ValueError.","triggerScenarios":"Decoding/converting a timestamp value whose subseconds field exceeds 10**precision - 1 for the configured precision, e.g. subseconds=123456789 with precision=6, or negative subseconds; reading data written with a higher precision than the LogicalType instance declares.","commonSituations":"Writer and reader disagree on timestamp precision (writer stored nanos, reader configured micros); corrupted or hand-edited data; cross-language pipelines where the Java side uses a different precision argument.","solutions":["Construct/decode the ParameterizedTimestamp with the precision actually used to write the data (match the writer's precision argument).","Truncate subseconds to the configured precision before conversion if lossy truncation is acceptable.","Re-write the data with a consistent precision if source data is corrupt."],"exampleFix":"// before\nlt = ParameterizedTimestamp(precision=3)\nts = lt.to_language_type(proto_ts)  # subseconds=123456 -> ValueError\n\n// after\nlt = ParameterizedTimestamp(precision=6)  # matches the data's precision\nts = lt.to_language_type(proto_ts)","handlingStrategy":"validation","validationCode":"def subseconds_fit(proto_ts, precision):\n    return 0 <= int(proto_ts.subseconds) < 10 ** precision","typeGuard":null,"tryCatchPattern":"try:\n    ts = lt.to_language_type(proto_ts)\nexcept ValueError:\n    # precision mismatch: rescale subseconds to the instance precision\n    scaled = int(proto_ts.subseconds) % (10 ** lt._precision)\n    ts = lt.to_language_type(proto_ts.__class__(seconds=proto_ts.seconds, subseconds=scaled, precision=lt._precision))","preventionTips":["Guarantee writer and reader use the same timestamp precision argument.","Validate incoming data ranges at ingestion, not at schema conversion.","Watch for cross-language (Java/Python) precision differences in pipeline contracts."],"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"}