apache/beam · error · ValueError

Invalid subseconds %d for Timestamp with precision %d.

Error message

Invalid subseconds %d for Timestamp with precision %d.

What it means

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.

Source

Thrown at sdks/python/apache_beam/typehints/schemas.py:1068

      return ParameterizedTimestampShortRepresentation
    return ParameterizedTimestampRepresentation

  @classmethod
  def language_type(cls):
    return Timestamp

  def to_representation_type(self, value: Timestamp):
    # Verify that the value can be represented exactly at this type's precision
    if value.precision() != self._precision:
      value = value.to_precision(self._precision)
    return self.representation_type()(value.seconds(), value.subseconds())

  def to_language_type(self, value) -> Timestamp:
    subseconds = int(value.subseconds)
    # Match Java's toInputType: out-of-range subseconds indicate data
    # corruption or a precision mismatch.
    if not 0 <= subseconds < 10**self._precision:
      raise ValueError(
          'Invalid subseconds %d for Timestamp with precision %d.' %
          (subseconds, self._precision))
    return Timestamp(
        seconds=int(value.seconds),
        subseconds=subseconds,
        precision=self._precision)

  @classmethod
  def argument_type(cls):
    return np.int32

  def argument(self):
    return self._precision

  @classmethod
  def _from_typing(cls, typ):
    # A bare Timestamp typehint has no precision; default to micros.
    return cls(Timestamp.MICROS_PRECISION)

View on GitHub (pinned to 12126d8942)

Solutions

1. Construct/decode the ParameterizedTimestamp with the precision actually used to write the data (match the writer's precision argument).
2. Truncate subseconds to the configured precision before conversion if lossy truncation is acceptable.
3. Re-write the data with a consistent precision if source data is corrupt.

Example fix

// before
lt = ParameterizedTimestamp(precision=3)
ts = lt.to_language_type(proto_ts)  # subseconds=123456 -> ValueError

// after
lt = ParameterizedTimestamp(precision=6)  # matches the data's precision
ts = lt.to_language_type(proto_ts)

def subseconds_fit(proto_ts, precision):
    return 0 <= int(proto_ts.subseconds) < 10 ** precision

try:
    ts = lt.to_language_type(proto_ts)
except ValueError:
    # precision mismatch: rescale subseconds to the instance precision
    scaled = int(proto_ts.subseconds) % (10 ** lt._precision)
    ts = lt.to_language_type(proto_ts.__class__(seconds=proto_ts.seconds, subseconds=scaled, precision=lt._precision))

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Timestamp precision must be between 0 and %d (inclusive), bu
• beam:logical_type:timestamp:v1 requires a precision argument
• set_watermark expects a Timestamp as input
• No timestamp in this context.
• timestamp not accessible in this context

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/10e13eddff34d7af. Report an issue: GitHub.