apache/beam · error · ValueError

%r has greater than microsecond precision, converting it to…

Error message

%r has greater than microsecond precision, converting it to micros may lose precision. Use to_precision(6, allow_lossy_conversion=True) to explicitly truncate it first, or use nanos instead.

What it means

apache_beam.utils.timestamp.Timestamp.micros raises ValueError when the timestamp was created with sub-microsecond (nanosecond) precision and the caller asks for the microsecond value. Reading `.micros` would silently truncate the extra digits, so the library forces you to either explicitly truncate with to_precision(6, allow_lossy_conversion=True) or read `.nanos` instead.

Solutions

1. Read `.nanos` instead of `.micros` if you need the full precision value.
2. Call ts.to_precision(6, allow_lossy_conversion=True).micros to explicitly truncate to microseconds.
3. Ensure upstream timestamps are constructed at microsecond precision if micros is the intended unit.

Example fix

// before
micros = ts.micros  # raises for nanosecond-precision ts
// after
micros = ts.to_precision(6, allow_lossy_conversion=True).micros
# or, without losing precision:
exact = ts.nanos

def safe_micros(ts):
    if ts.precision > 6:
        ts = ts.to_precision(6, allow_lossy_conversion=True)
    return ts.micros

def has_micro_precision(ts):
    return ts.precision <= 6

try:
    micros = ts.micros
except ValueError:
    micros = ts.nanos // 1000  # explicit truncation

When it happens

Trigger: Accessing the `micros` property on any Timestamp whose _precision exceeds Timestamp.MICROS_PRECISION (6), e.g. a nanosecond-precision Timestamp from Timestamp.of, arithmetic, or to_precision(9).

Common situations: Processing event timestamps coming from sources with nanosecond resolution (e.g. fuzzer/DoFn tests, protobuf Timestamp with non-zero nanos, data from formats like Spanner or high-resolution clocks), then reading `.micros` in a DoFn or test assertion.

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

• Converting %r to datetime truncates it to microseconds. Set…
• %r cannot be represented exactly at precision
• The difference of %r and %r has sub-microsecond precision…
• The remainder of %r modulo %r has sub-microsecond…
• Bad timestamp value for message

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

Appendix: source

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

    """Returns the timestamp in seconds."""
    return self._seconds

  def subseconds(self) -> int:
    """Returns the fraction of a second, in units of 10**-precision seconds.

    Always non-negative and less than 10**precision
    """
    return self._subseconds

  def precision(self) -> int:
    """Returns the precision of this Timestamp."""
    return self._precision

  @property
  def micros(self) -> int:
    """Returns the total number of microseconds since the epoch."""
    if self._precision > Timestamp.MICROS_PRECISION:
      raise ValueError(
          '%r has greater than microsecond precision, converting it to '
          'micros may lose precision. Use to_precision(6, '
          'allow_lossy_conversion=True) to explicitly truncate it first, '
          'or use nanos instead.' % self)
    return self._total(Timestamp.MICROS_PRECISION)

  @property
  def nanos(self) -> int:
    """Returns the total number of nanoseconds since the epoch."""
    return self._total(Timestamp.NANOS_PRECISION)

  def to_precision(
      self,
      precision: int,
      allow_lossy_conversion: bool = False) -> 'Timestamp':
    """Returns this Timestamp converted to the given precision.

    Increasing precision is always lossless. Decreasing precision raises

View on GitHub (pinned to 12126d8942)