apache/beam · error · ValueError

Timestamp precision must be between 0 and

Error message

Timestamp precision must be between 0 and %d (inclusive), but was %d.

What it means

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.

Solutions

1. Use precision <= 9 (NANOS_PRECISION); truncate finer digits
2. Clamp: precision = max(0, min(precision, Timestamp.NANOS_PRECISION))
3. For sub-nanosecond data, pre-round the subseconds value instead of raising precision

Example fix

// before
Timestamp(seconds=s, precision=len(digits))  # digits may be 12 long
// after
precision = min(len(digits), Timestamp.NANOS_PRECISION)
Timestamp(seconds=s, precision=precision)

if not 0 <= precision <= Timestamp.NANOS_PRECISION:
    precision = max(0, min(precision, Timestamp.NANOS_PRECISION))

try:
    ts = Timestamp(seconds=s, precision=p)
except ValueError as e:
    log.warning('clamping precision: %s', e)
    ts = Timestamp(seconds=s, precision=min(p, Timestamp.NANOS_PRECISION))

When it happens

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

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

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

• Could not parse RFC 3339 string
• Could not parse RFC 3339 string
• micros and subseconds are mutually exclusive, got micros=
• micros implies microsecond precision (6) but precision was
• No timestamp in this context.

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

Appendix: source

Thrown at sdks/python/apache_beam/utils/timestamp.py:93

  def __init__(
      self,
      seconds: Union[int, float] = 0,
      subseconds: Union[int, float] = 0,
      precision: int = MICROS_PRECISION,
      *,
      micros: Optional[Union[int, float]] = None) -> None:
    if not isinstance(seconds, (int, float)):
      raise TypeError(
          'Cannot interpret %s %s as seconds.' % (seconds, type(seconds)))
    if not isinstance(subseconds, (int, float)):
      raise TypeError(
          'Cannot interpret %s %s as subseconds.' %
          (subseconds, type(subseconds)))
    if not isinstance(precision, int):
      raise TypeError(
          'Cannot interpret %s %s as precision.' % (precision, type(precision)))
    if not 0 <= precision <= Timestamp.NANOS_PRECISION:
      raise ValueError(
          'Timestamp precision must be between 0 and %d (inclusive), '
          'but was %d.' % (Timestamp.NANOS_PRECISION, precision))
    if micros is not None:
      if not isinstance(micros, (int, float)):
        raise TypeError(
            'Cannot interpret %s %s as micros.' % (micros, type(micros)))
      if subseconds:
        raise ValueError(
            'micros and subseconds are mutually exclusive, got micros=%s, '
            'subseconds=%s.' % (micros, subseconds))
      if precision != Timestamp.MICROS_PRECISION:
        raise ValueError(
            'micros implies microsecond precision (6) but precision was %d; '
            'use subseconds instead.' % precision)
      subseconds = micros
    self._precision = precision
    total = int(seconds * _POW_10[precision]) + int(subseconds)
    self._seconds, self._subseconds = divmod(total, _POW_10[precision])

View on GitHub (pinned to 12126d8942)