{"record":{"id":"a8d268b779fb901e","repo":"apache/beam","slug":"mode-axis-columns-is-not-supported-because-it-produces-a","errorCode":null,"errorMessage":"mode(axis=columns) is not supported because it produces a variable number of columns depending on the data.","messagePattern":"mode\\(axis=columns\\) is not supported because it produces a variable number of columns depending on the data\\.","errorType":"exception","errorClass":"WontImplementError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/frames.py","lineNumber":3303,"sourceCode":"            requires_partition_by=partitionings.Arbitrary(),\n            preserves_partition_by=partitionings.Arbitrary(),\n            proxy=proxy))\n\n  __matmul__ = dot\n\n  @frame_base.with_docs_from(pd.DataFrame)\n  def mode(self, axis=0, *args, **kwargs):\n    \"\"\"mode with axis=\"columns\" is not implemented because it produces\n    non-deferred columns.\n\n    mode with axis=\"index\" is not currently parallelizable. An approximate,\n    parallelizable implementation of mode may be added in the future\n    (`Issue 20946 <https://github.com/apache/beam/issues/20946>`_).\"\"\"\n\n    if axis == 1 or axis == 'columns':\n      # Number of columns is max(number mode values for each row), so we can't\n      # determine how many there will be before looking at the data.\n      raise frame_base.WontImplementError(\n          \"mode(axis=columns) is not supported because it produces a variable \"\n          \"number of columns depending on the data.\",\n          reason=\"non-deferred-columns\")\n    return frame_base.DeferredFrame.wrap(\n        expressions.ComputedExpression(\n            'mode',\n            lambda df: df.mode(*args, **kwargs),\n            [self._expr],\n            #TODO(https://github.com/apache/beam/issues/20946):\n            # Can we add an approximate implementation?\n            requires_partition_by=partitionings.Singleton(reason=(\n                \"mode(axis='index') cannot currently be parallelized. See \"\n                \"https://github.com/apache/beam/issues/20946 tracking the \"\n                \"possble addition of an approximate, parallelizable \"\n                \"implementation of mode.\"\n            )),\n            preserves_partition_by=partitionings.Singleton()))\n","sourceCodeStart":3285,"sourceCodeEnd":3321,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/frames.py#L3285-L3321","documentation":"apache_beam.dataframe raises WontImplementError for DataFrame.mode(axis=1/'columns') because row-wise mode can yield a variable number of winning values per row, so the output column count cannot be known lazily before the data is inspected. Beam's deferred dataframe API requires a statically-known schema (deferred columns). A parallelizable implementation is tracked in Beam issue 20946.","triggerScenarios":"Calling df.mode() with axis=1 or axis='columns' on a Beam DeferredDataFrame.","commonSituations":"Porting pandas code that computes per-row most-frequent values directly to Beam pipelines; users unaware Beam requires static column schemas.","solutions":["Use axis=0 (default) mode, which is supported, if column-wise mode fits the problem.","Compute row-wise mode manually with apply/row-wise expressions that return a fixed schema, or pad results to a fixed width.","Fall back to a non-distributed pandas computation if the data fits in memory (collect via to_pandas).","Track Beam issue 20946 for a future parallelizable implementation."],"exampleFix":"// before\nmodes = df.mode(axis='columns')\n// after\nmodes = df.mode()  # axis=0, per-column mode","handlingStrategy":"validation","validationCode":"def check_mode_axis(axis):\n    if axis in (1, 'columns'):\n        raise ValueError(\"Beam DataFrames do not support mode(axis='columns')\")","typeGuard":"def mode_supported(axis) -> bool:\n    return axis not in (1, 'columns')","tryCatchPattern":"from apache_beam.dataframe import frame_base\ntry:\n    modes = df.mode(axis='columns')\nexcept frame_base.WontImplementError:\n    modes = df.mode()","preventionTips":["Remember Beam DataFrames need statically-known schemas: avoid operations that produce variable column counts.","Prefer axis=0 aggregations in Beam pipelines.","Check the Beam pandas API docs' supported/unsupported matrix before porting."],"tags":["pandas","apache-beam","dataframe","unsupported-operation"],"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"}