{"record":{"id":"416b65c5f49463fd","repo":"apache/beam","slug":"shift-axis-axis-r-is-only-supported-with-freq-defined-and","errorCode":null,"errorMessage":"shift(axis={axis!r}) is only supported with freq defined, and fill_value undefined (got freq={freq!r},fill_value={fill_value!r}). Other configurations are sensitive to the order of the data because they require populating shifted rows with `fill_value`.","messagePattern":"shift\\(axis=(.+?)\\) is only supported with freq defined, and fill_value undefined \\(got freq=(.+?),fill_value=(.+?)\\)\\. Other configurations are sensitive to the order of the data because they require populating shifted rows with `fill_value`\\.","errorType":"exception","errorClass":"WontImplementError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":3766,"sourceCode":"    )\n\n  select_dtypes = frame_base._elementwise_method('select_dtypes',\n                                                 base=pd.DataFrame)\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 shift(self, axis, freq, **kwargs):\n    \"\"\"shift with ``axis=\"index\" is only supported with ``freq`` specified and\n    ``fill_value`` undefined. Other configurations make this operation\n    order-sensitive.\"\"\"\n    if axis in (1, 'columns'):\n      preserves = partitionings.Arbitrary()\n      proxy = None\n    else:\n      if freq is None or 'fill_value' in kwargs:\n        fill_value = kwargs.get('fill_value', 'NOT SET')\n        raise frame_base.WontImplementError(\n            f\"shift(axis={axis!r}) is only supported with freq defined, and \"\n            f\"fill_value undefined (got freq={freq!r},\"\n            f\"fill_value={fill_value!r}). Other configurations are sensitive \"\n            \"to the order of the data because they require populating shifted \"\n            \"rows with `fill_value`.\",\n            reason=\"order-sensitive\")\n      # proxy generation fails in pandas <1.2\n      # Seems due to https://github.com/pandas-dev/pandas/issues/14811,\n      # bug with shift on empty indexes.\n      # Fortunately the proxy should be identical to the input.\n      proxy = self._expr.proxy().copy()\n\n\n      # index is modified, so no partitioning is preserved.\n      preserves = partitionings.Singleton()\n\n    return frame_base.DeferredFrame.wrap(\n        expressions.ComputedExpression(","sourceCodeStart":3748,"sourceCodeEnd":3784,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L3748-L3784","documentation":"Beam's DataFrame.shift throws WontImplementError for the row axis unless freq is given and fill_value is left undefined. Without freq, shifting fills vacated positions with fill_value, which depends on positional row order and is not preserved in distributed execution.","triggerScenarios":"Calling df.shift(periods) or df.shift(..., fill_value=...) without freq on a DeferredDataFrame (row axis), or shift with axis='columns' variants lacking freq.","commonSituations":"Time-series code ported from pandas that shifts by positional periods instead of by time frequency; custom fill values for leading NaNs.","solutions":["Provide a freq argument (e.g. freq='D') so the shift is index-based and order-independent.","Remove the fill_value argument; the default fill (via freq shifting) is order-safe.","Implement a windowing/DoFn-based positional shift in core Beam if truly needed.","Fall back to local pandas for positional shifts."],"exampleFix":"// before\nshifted = df.shift(1, fill_value=0)\n// after\nshifted = df.shift(1, freq='D')","handlingStrategy":"validation","validationCode":"def check_shift_args(freq, kwargs, axis):\n    if axis not in (1, 'columns') and (freq is None or 'fill_value' in kwargs):\n        raise ValueError('shift requires freq and no fill_value on the row axis in Beam')","typeGuard":"def shift_supported(freq, kwargs, axis) -> bool:\n    return axis in (1, 'columns') or (freq is not None and 'fill_value' not in kwargs)","tryCatchPattern":"from apache_beam.dataframe import frame_base\ntry:\n    shifted = df.shift(1, fill_value=0)\nexcept frame_base.WontImplementError:\n    shifted = df.shift(1, freq='D')","preventionTips":["Shift by time frequency (freq=...), not by position, in Beam pipelines.","Never pass fill_value to shift in Beam code.","Use Beam windowing primitives for order-based time operations."],"tags":["pandas","apache-beam","dataframe","order-sensitive"],"backgroundTag":"invalid-argument-value","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"}