apache/beam · error · WontImplementError

tz_localize(ambiguous=ndarray) is not supported because it…

Error message

tz_localize(ambiguous=ndarray) is not supported because it makes this operation sensitive to the order of the data. Please use a DeferredSeries instead.

What it means

tz_localize accepts an ambiguous argument to resolve DST-ambiguous timestamps; supplying it as a raw numpy array encodes per-row decisions keyed by data order, which is order-sensitive in Beam. The API tells you to pass a DeferredSeries instead, which aligns element-wise regardless of order.

Solutions

Convert the ambiguity mask to a deferred Series aligned by index and pass that instead of an ndarray.
Use ambiguous='NaT' or a scalar boolean (True/False) which is order-independent.
Use ambiguous='infer' — no, that also raises; instead localize with a fixed rule like ambiguous=True/False.
Do the localization after to_pandas() if array-based ambiguity is essential.

Example fix

// before
s = s.tz_localize('US/Eastern', ambiguous=np.array([True, False]))
// after
mask = pd.Series([True, False], index=s.index)  # as a deferred Series
s = s.tz_localize('US/Eastern', ambiguous=deferred_mask)

Defensive patterns

Strategy: type-guard

Validate before calling

if isinstance(ambiguous, np.ndarray):
    raise ValueError('Pass ambiguous as a DeferredSeries or a scalar, not an ndarray')

Type guard

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

Try / catch

try:
    s = s.tz_localize(tz, ambiguous=mask_array)
except frame_base.WontImplementError:
    s = s.tz_localize(tz, ambiguous=deferred_mask_series)

Prevention

Represent ambiguity masks as pandas/deferred Series aligned by index
Prefer scalar ambiguous=True/False or 'NaT' when a single rule fits
Check types of ambiguous before calling tz_localize

When it happens

Trigger: series.tz_localize('UTC', ambiguous=np.array([True, False, ...])) — ambiguous given as an ndarray — on a deferred frame/series.

Common situations: Localizing timestamps around DST fall-back transitions; pandas code that precomputed an ambiguity mask as an array; time-series ingestion pipelines migrated to Beam.

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/943f687767eec08d. Report an issue: GitHub.

Appendix: source

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

              "requires collecting all data on a single node."))
    return frame_base.DeferredFrame.wrap(
        expressions.ComputedExpression(
            'replace', lambda df: df.replace(
                to_replace=to_replace, value=value, limit=limit, method=method,
                **kwargs), [self._expr],
            preserves_partition_by=partitionings.Arbitrary(),
            requires_partition_by=requires_partition_by))

  @frame_base.with_docs_from(pd.DataFrame)
  @frame_base.args_to_kwargs(pd.DataFrame)
  @frame_base.populate_defaults(pd.DataFrame)
  def tz_localize(self, ambiguous, **kwargs):
    """``ambiguous`` cannot be set to ``"infer"`` as its semantics are
    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")

View on GitHub (pinned to 12126d8942)