{"record":{"id":"e8ae86e67da5a6ff","repo":"apache/beam","slug":"tz-localize-ambiguous-ambiguous-r-is-not-allowed-because-it","errorCode":null,"errorMessage":"tz_localize(ambiguous={ambiguous!r}) is not allowed because it makes this operation sensitive to the order of the data.","messagePattern":"tz_localize\\(ambiguous=(.+?)\\) is not allowed because it makes this operation sensitive to the order of the data\\.","errorType":"exception","errorClass":"WontImplementError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":727,"sourceCode":"    order-sensitive. Similarly, specifying ``ambiguous`` as an\n    :class:`~numpy.ndarray` is order-sensitive, but you can achieve similar\n    functionality by specifying ``ambiguous`` as a Series.\"\"\"\n    if isinstance(ambiguous, np.ndarray):\n      raise frame_base.WontImplementError(\n          \"tz_localize(ambiguous=ndarray) is not supported because it makes \"\n          \"this operation sensitive to the order of the data. Please use a \"\n          \"DeferredSeries instead.\",\n          reason=\"order-sensitive\")\n    elif isinstance(ambiguous, frame_base.DeferredFrame):\n      return frame_base.DeferredFrame.wrap(\n          expressions.ComputedExpression(\n              'tz_localize', lambda df, ambiguous: df.tz_localize(\n                  ambiguous=ambiguous, **kwargs), [self._expr, ambiguous._expr],\n              requires_partition_by=partitionings.Index(),\n              preserves_partition_by=partitionings.Singleton()))\n    elif ambiguous == 'infer':\n      # infer attempts to infer based on the order of the timestamps\n      raise frame_base.WontImplementError(\n          f\"tz_localize(ambiguous={ambiguous!r}) is not allowed because it \"\n          \"makes this operation sensitive to the order of the data.\",\n          reason=\"order-sensitive\")\n\n    return frame_base.DeferredFrame.wrap(\n        expressions.ComputedExpression(\n            'tz_localize',\n            lambda df: df.tz_localize(ambiguous=ambiguous, **kwargs),\n            [self._expr],\n            requires_partition_by=partitionings.Arbitrary(),\n            preserves_partition_by=partitionings.Singleton()))\n\n  @property  # type: ignore\n  @frame_base.with_docs_from(pd.DataFrame)\n  def size(self):\n    sizes = expressions.ComputedExpression(\n        'get_sizes',\n        # Wrap scalar results in a Series for easier concatenation later","sourceCodeStart":709,"sourceCodeEnd":745,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L709-L745","documentation":"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.","triggerScenarios":"series.tz_localize(tz, ambiguous='infer') on a deferred frame/series with naive timestamps spanning a DST fall-back.","commonSituations":"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.","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."],"exampleFix":"// before\ns = s.tz_localize('US/Eastern', ambiguous='infer')\n// after\ns = s.tz_localize('US/Eastern', ambiguous=False)  # or a deferred boolean Series","handlingStrategy":"validation","validationCode":"if ambiguous == 'infer':\n    raise ValueError('ambiguous=\\'infer\\' is order-sensitive and unsupported in Beam')","typeGuard":"def tz_args_supported(ambiguous) -> bool:\n    return ambiguous != 'infer' and not isinstance(ambiguous, np.ndarray)","tryCatchPattern":"try:\n    s = s.tz_localize(tz, ambiguous='infer')\nexcept frame_base.WontImplementError:\n    s = s.tz_localize(tz, ambiguous=False)","preventionTips":["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"],"tags":["apache-beam","dataframe","pandas","timezone","dst"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}