{"record":{"id":"943f687767eec08d","repo":"apache/beam","slug":"tz-localize-ambiguous-ndarray-is-not-supported-because-it","errorCode":null,"errorMessage":"tz_localize(ambiguous=ndarray) is not supported because it makes this operation sensitive to the order of the data. Please use a DeferredSeries instead.","messagePattern":"tz_localize\\(ambiguous=ndarray\\) is not supported because it makes this operation sensitive to the order of the data\\. Please use a DeferredSeries instead\\.","errorType":"exception","errorClass":"WontImplementError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":713,"sourceCode":"              \"requires collecting all data on a single node.\"))\n    return frame_base.DeferredFrame.wrap(\n        expressions.ComputedExpression(\n            'replace', lambda df: df.replace(\n                to_replace=to_replace, value=value, limit=limit, method=method,\n                **kwargs), [self._expr],\n            preserves_partition_by=partitionings.Arbitrary(),\n            requires_partition_by=requires_partition_by))\n\n  @frame_base.with_docs_from(pd.DataFrame)\n  @frame_base.args_to_kwargs(pd.DataFrame)\n  @frame_base.populate_defaults(pd.DataFrame)\n  def tz_localize(self, ambiguous, **kwargs):\n    \"\"\"``ambiguous`` cannot be set to ``\"infer\"`` as its semantics are\n    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","sourceCodeStart":695,"sourceCodeEnd":731,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L695-L731","documentation":"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.","triggerScenarios":"series.tz_localize('UTC', ambiguous=np.array([True, False, ...])) — ambiguous given as an ndarray — on a deferred frame/series.","commonSituations":"Localizing timestamps around DST fall-back transitions; pandas code that precomputed an ambiguity mask as an array; time-series ingestion pipelines migrated to Beam.","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."],"exampleFix":"// before\ns = s.tz_localize('US/Eastern', ambiguous=np.array([True, False]))\n// after\nmask = pd.Series([True, False], index=s.index)  # as a deferred Series\ns = s.tz_localize('US/Eastern', ambiguous=deferred_mask)","handlingStrategy":"type-guard","validationCode":"if isinstance(ambiguous, np.ndarray):\n    raise ValueError('Pass ambiguous as a DeferredSeries or a scalar, not an ndarray')","typeGuard":"def ambiguous_is_supported(ambiguous) -> bool:\n    return not isinstance(ambiguous, np.ndarray) and ambiguous != 'infer'","tryCatchPattern":"try:\n    s = s.tz_localize(tz, ambiguous=mask_array)\nexcept frame_base.WontImplementError:\n    s = s.tz_localize(tz, ambiguous=deferred_mask_series)","preventionTips":["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"],"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"}