apache/beam · error · WontImplementError

tz_localize(ambiguous= ) is not allowed because it makes…

Error message

tz_localize(ambiguous={ambiguous!r}) is not allowed because it makes this operation sensitive to the order of the data.

What it means

tz_localize(ambiguous='infer') determines DST ambiguity from the ORDER of timestamps, which Beam cannot rely on in distributed execution. The API explicitly forbids 'infer' with a WontImplementError; a DeferredSeries or scalar ambiguous value must be used instead.

Solutions

Pass a scalar for ambiguous (True or False) that correctly describes the whole batch.
Pass an aligned DeferredSeries of booleans as ambiguous.
Choose a timezone/rule that avoids ambiguity, or drop ambiguous entirely when the data has no DST overlap.
Collect the series to pandas (to_pandas) and localize there if inference is truly needed.

Example fix

// before
s = s.tz_localize('US/Eastern', ambiguous='infer')
// after
s = s.tz_localize('US/Eastern', ambiguous=False)  # or a deferred boolean Series

Defensive patterns

Strategy: validation

Validate before calling

if ambiguous == 'infer':
    raise ValueError('ambiguous=\'infer\' is order-sensitive and unsupported in Beam')

Type guard

def tz_args_supported(ambiguous) -> bool:
    return ambiguous != 'infer' and not isinstance(ambiguous, np.ndarray)

Try / catch

try:
    s = s.tz_localize(tz, ambiguous='infer')
except frame_base.WontImplementError:
    s = s.tz_localize(tz, ambiguous=False)

Prevention

Avoid ambiguous='infer' anywhere in Beam pipelines
Choose explicit DST-resolution rules (scalar or deferred Series)
Check whether timestamps can even straddle a DST fall-back before localizing

When it happens

Trigger: series.tz_localize(tz, ambiguous='infer') on a deferred frame/series with naive timestamps spanning a DST fall-back.

Common situations: Localizing log/event timestamps collected around the repeated hour of a DST transition; pandas time-series code ported to Beam; ETL jobs where 'infer' was the pandas default habit.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/dataframe/frames.py:727

    order-sensitive. Similarly, specifying ``ambiguous`` as an
    :class:`~numpy.ndarray` is order-sensitive, but you can achieve similar
    functionality by specifying ``ambiguous`` as a Series."""
    if isinstance(ambiguous, np.ndarray):
      raise frame_base.WontImplementError(
          "tz_localize(ambiguous=ndarray) is not supported because it makes "
          "this operation sensitive to the order of the data. Please use a "
          "DeferredSeries instead.",
          reason="order-sensitive")
    elif isinstance(ambiguous, frame_base.DeferredFrame):
      return frame_base.DeferredFrame.wrap(
          expressions.ComputedExpression(
              'tz_localize', lambda df, ambiguous: df.tz_localize(
                  ambiguous=ambiguous, **kwargs), [self._expr, ambiguous._expr],
              requires_partition_by=partitionings.Index(),
              preserves_partition_by=partitionings.Singleton()))
    elif ambiguous == 'infer':
      # infer attempts to infer based on the order of the timestamps
      raise frame_base.WontImplementError(
          f"tz_localize(ambiguous={ambiguous!r}) is not allowed because it "
          "makes this operation sensitive to the order of the data.",
          reason="order-sensitive")

    return frame_base.DeferredFrame.wrap(
        expressions.ComputedExpression(
            'tz_localize',
            lambda df: df.tz_localize(ambiguous=ambiguous, **kwargs),
            [self._expr],
            requires_partition_by=partitionings.Arbitrary(),
            preserves_partition_by=partitionings.Singleton()))

  @property  # type: ignore
  @frame_base.with_docs_from(pd.DataFrame)
  def size(self):
    sizes = expressions.ComputedExpression(
        'get_sizes',
        # Wrap scalar results in a Series for easier concatenation later

View on GitHub (pinned to 12126d8942)