apache/beam · error · ValueError

beam:logical_type:timestamp:v1 requires a precision argument

Error message

beam:logical_type:timestamp:v1 requires a precision argument.

What it means

ParameterizedTimestamp (beam:logical_type:timestamp:v1) requires an explicit precision argument; constructing it with precision=None raises ValueError. A timestamp:v1 proto without its precision argument is considered malformed, since decoding at a guessed precision would silently misscale subseconds.

Source

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

  represent the fraction of a second, e.g. 3 for milliseconds, 6 for
  microseconds, 9 for nanoseconds.

  Values are represented as a row of ``seconds`` (INT64, floored seconds
  since the epoch) and ``subseconds`` (units of 10**-precision seconds,
  always in ``[0, 10**precision)``.
  ``subseconds`` is an INT16 field for precision < 5 and an INT32
  field otherwise.

  Note: Timestamp originating from Python to xlang still defaults to
  MicrosInstant for backwards compatibility. To override the mapping of
  Timestamp to this logical type, re-register using
  :func:`~LogicalType.register_logical_type(ParameterizedTimestamp)`.
  """
  def __init__(self, precision: Optional[int] = None) -> None:
    if precision is None:
      # A timestamp:v1 proto without its precision argument is malformed;
      # decoding at a guessed precision would silently misscale subseconds.
      raise ValueError(
          'beam:logical_type:timestamp:v1 requires a precision argument.')
    # The argument arrives as np.int32 when decoded from a schema proto.
    precision = int(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))
    self._precision = precision

  @classmethod
  def urn(cls):
    return common_urns.timestamp.urn

  def representation_type(self) -> type:  # type: ignore[override]
    # Unlike other logical types, the representation depends on the
    # argument, so this is an instance method rather than a classmethod.
    if self._precision < _TIMESTAMP_SHORT_PRECISION_LIMIT:
      return ParameterizedTimestampShortRepresentation

View on GitHub (pinned to 12126d8942)

Solutions

Pass an explicit precision (0-9) when constructing ParameterizedTimestamp, e.g. ParameterizedTimestamp(precision=6).
Ensure the schema proto includes both argument_type and argument for the timestamp logical type before decoding.
Use plain Timestamp/NanosDuration types instead of the parameterized logical type if no precision is needed.

Example fix

// before
lt = ParameterizedTimestamp()  # ValueError

// after
lt = ParameterizedTimestamp(precision=6)  # microseconds

Defensive patterns

Strategy: validation

Validate before calling

def build_parameterized_timestamp(precision):
    if precision is None:
        raise ValueError("precision is required for beam:logical_type:timestamp:v1")
    return ParameterizedTimestamp(precision=int(precision))

Try / catch

try:
    lt = ParameterizedTimestamp(precision)
except ValueError:
    lt = ParameterizedTimestamp(precision=6)  # default to micros if proto lacked precision

Prevention

Always pass precision explicitly when constructing ParameterizedTimestamp.
Ensure schema protos carry both argument_type and argument for timestamp logical types.
Document the precision used by your pipeline so readers can reconstruct it.

When it happens

Trigger: Instantiating ParameterizedTimestamp() or ParameterizedTimestamp(None); decoding a logical_type proto whose argument/argument_type fields are missing so the constructor is called with no precision.

Common situations: Hand-building schema protos for timestamp logical types and forgetting the argument; a runner or older SDK emitting timestamp:v1 without precision; tests constructing the class directly.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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