pola-rs/polars · error · ValueError

matrix columns should be equal to list used to determine col

Error message

matrix columns should be equal to list used to determine column names

What it means

In multi-column __setitem__ (df[['C', 'D']] = matrix), after the 2-D check passes, the matrix's second dimension must equal the number of column names supplied. A mismatch means columns would be silently dropped or missing, so the assignment aborts with ValueError before mutating anything.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:1559

        """
        # df["foo"] = series
        if isinstance(key, str):
            msg = (
                "DataFrame object does not support `Series` assignment by index"
                "\n\nUse `DataFrame.with_columns`."
            )
            raise TypeError(msg)

        # df[["C", "D"]]
        elif isinstance(key, list):
            # TODO: Use python sequence constructors
            value = np.array(value)
            if value.ndim != 2:
                msg = "can only set multiple columns with 2D matrix"
                raise ValueError(msg)
            if value.shape[1] != len(key):
                msg = "matrix columns should be equal to list used to determine column names"
                raise ValueError(msg)

            # TODO: we can parallelize this by calling from_numpy
            columns = []
            for i, name in enumerate(key):
                columns.append(pl.Series(name, value[:, i]))
            self._df = self.with_columns(columns)._df

        # df[a, b]
        elif isinstance(key, tuple):
            row_selection, col_selection = key

            if (
                isinstance(row_selection, pl.Series) and row_selection.dtype == Boolean
            ) or is_bool_sequence(row_selection):
                msg = (
                    "not allowed to set DataFrame by boolean mask in the row position"
                    "\n\nConsider using `DataFrame.with_columns`."
                )

View on GitHub (pinned to df599052da)

Solutions

1. Align the names to the matrix: assert arr.shape[1] == len(names), or slice arr = arr[:, :len(names)]
2. If the matrix is transposed, fix orientation: arr = arr.T so axis 1 is columns
3. Prefer explicit construction: df = df.with_columns([pl.Series(name, arr[:, i]) for i, name in enumerate(names)])

Example fix

# before
names = ['C', 'D']
df[names] = np.ones((df.height, 3))  # 3 cols vs 2 names

# after
names = ['C', 'D']
matrix = np.ones((df.height, len(names)))
df[names] = matrix

import numpy as np

value = np.asarray(value)
assert value.ndim == 2 and value.shape[1] == len(keys), (value.shape, keys)
df[keys] = value

When it happens

Trigger: df[['C', 'D']] = arr where arr.shape == (n, 3) or (n, 1); assigning a 3-wide matrix to ['C', 'D', 'E'] list of two names; off-by-one column lists after editing code.

Common situations: Generated code where the key list and matrix width come from different sources; refactors that add a column to the matrix but not the names; transposed matrices (shape (k, n) instead of (n, k)).

Related errors

• can only set multiple columns with 2D matrix
• data does not match the number of columns
• dimensions of columns arg ({len(columns)}) must match data d
• cannot create DataFrame from zero-dimensional array
• cannot create DataFrame from array with more than two dimens

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/736f3f65be66125e. Report an issue: GitHub.