{"record":{"id":"c23b4f498326b8a7","repo":"apache/beam","slug":"insert-value-list-is-not-supported-because-it-joins-the","errorCode":null,"errorMessage":"insert(value=list) is not supported because it joins the input list to the deferred DataFrame based on the order of the data.","messagePattern":"insert\\(value=list\\) is not supported because it joins the input list to the deferred DataFrame based on the order of the data\\.","errorType":"exception","errorClass":"WontImplementError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":2763,"sourceCode":"    # ignoring the index will not preserve it\n    preserves = (partitionings.Singleton() if ignore_index\n                 else partitionings.Index())\n    return frame_base.DeferredFrame.wrap(\n        expressions.ComputedExpression(\n            'explode',\n            lambda df: df.explode(column, ignore_index),\n            [self._expr],\n            preserves_partition_by=preserves,\n            requires_partition_by=partitionings.Arbitrary()))\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 insert(self, value, **kwargs):\n    \"\"\"``value`` cannot be a ``List`` because aligning it with this\n    DeferredDataFrame is order-sensitive.\"\"\"\n    if isinstance(value, list):\n      raise frame_base.WontImplementError(\n          \"insert(value=list) is not supported because it joins the input \"\n          \"list to the deferred DataFrame based on the order of the data.\",\n          reason=\"order-sensitive\")\n\n    if isinstance(value, pd.core.generic.NDFrame):\n      value = frame_base.DeferredFrame.wrap(\n          expressions.ConstantExpression(value))\n\n    if isinstance(value, frame_base.DeferredFrame):\n      def func_zip(df, value):\n        df = df.copy()\n        df.insert(value=value, **kwargs)\n        return df\n\n      inserted = frame_base.DeferredFrame.wrap(\n          expressions.ComputedExpression(\n              'insert',\n              func_zip,","sourceCodeStart":2745,"sourceCodeEnd":2781,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L2745-L2781","documentation":"DeferredDataFrame.insert refuses `value` given as a Python list. Inserting a list requires aligning it element-by-element with the frame's rows by position, which is order-sensitive in a distributed, unordered pipeline, so Beam raises WontImplementError.","triggerScenarios":"Calling `ddf.insert(loc, column, [1, 2, 3])` (or any list value) on a DeferredDataFrame.","commonSituations":"Porting notebook pandas code that inserts a computed list as a new column into a Beam DataFrame pipeline.","solutions":["Pass a DeferredSeries (wrapped via frame_base.DeferredFrame.wrap / constructed in the pipeline) instead of a list.","Pass a scalar — Beam supports scalar broadcast for insert since it is order-independent.","Compute the column before deferring the frame, or derive it from existing columns elementwise."],"exampleFix":"// before\nddf.insert(0, 'id', [101, 102, 103])\n\n// after\nddf.insert(0, 'id', 0)  # scalar, or pass a DeferredSeries built in-pipeline","handlingStrategy":"validation","validationCode":"if isinstance(value, list):\n    raise ValueError('insert(value=list) unsupported in Beam; pass a scalar or DeferredSeries')","typeGuard":"def is_insertable(value) -> bool:\n    return not isinstance(value, list)  # scalar or NDFrame/DeferredFrame ok","tryCatchPattern":"from apache_beam.dataframe import frame_base\ntry:\n    ddf.insert(0, 'col', value)\nexcept frame_base.WontImplementError:\n    ddf.insert(0, 'col', 0)  # scalar fallback or precomputed DeferredSeries","preventionTips":["Replace list-valued inserts with scalars or in-pipeline DeferredSeries.","Compute new columns before wrapping data into a Beam DataFrame transform.","Note the docstring: value cannot be a List because alignment is order-sensitive."],"tags":["pandas","apache-beam","dataframe","order-sensitive"],"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"}