cannot create DataFrame from array with more than two dimens

Error message

cannot create DataFrame from array with more than two dimensions; shape = {shape}

What it means

numpy_to_pydf rejects NumPy arrays with more than two dimensions. A polars DataFrame is strictly 2-D (rows × columns); a (2, 3, 4) tensor has no unambiguous mapping, so the constructor raises this ValueError instead of guessing.

Source

Thrown at py-polars/src/polars/_utils/construction/dataframe.py:1278

                    orient = "col"
                    n_columns = n_schema_cols
                else:
                    orient = "row"
                    n_columns = shape[1]

            elif orient == "row":
                n_columns = shape[1]
            elif orient == "col":
                n_columns = shape[0]
            else:
                msg = f"`orient` must be one of {{'col', 'row', None}}, got {orient!r}"
                raise ValueError(msg)
        else:
            if shape == ():
                msg = "cannot create DataFrame from zero-dimensional array"
            else:
                msg = f"cannot create DataFrame from array with more than two dimensions; shape = {shape}"
            raise ValueError(msg)

    if schema is not None and len(schema) != n_columns:
        if (n_schema_cols := len(schema)) != 1:
            msg = f"dimensions of `schema` ({n_schema_cols}) must match data dimensions ({n_columns})"
            raise ValueError(msg)
        n_columns = n_schema_cols

    column_names, schema_overrides = _unpack_schema(
        schema, schema_overrides=schema_overrides, n_expected=n_columns
    )

    # Convert data to series
    if structured_array:
        data_series = [
            pl.Series(
                name=series_name,
                values=data[record_name],
                dtype=schema_overrides.get(record_name),

View on GitHub (pinned to df599052da)

Solutions

Flatten to 2D: arr.reshape(-1, arr.shape[-1]) (stacking leading dims) or arr.reshape(arr.shape[0], -1).
Keep nesting as a List column: pl.DataFrame({"tensor": arr.tolist()}).
Create one DataFrame per 2D slice and pl.concat them with a batch-index column.

Example fix

// before
df = pl.DataFrame(embeddings)  # shape (32, 10, 768)

// after
df = pl.DataFrame(embeddings.reshape(-1, embeddings.shape[-1]))  # (320, 768)
// or: df = pl.DataFrame({"emb": embeddings.tolist()})  # List(Float64) column

Defensive patterns

Strategy: validation

Validate before calling

arr = np.asarray(value)
if arr.ndim > 2:
    arr = arr.reshape(-1, arr.shape[-1])  # or keep as list column: arr.tolist()
df = pl.DataFrame(arr)

Type guard

def is_dataframe_shaped(arr: np.ndarray) -> bool:
    return arr.ndim <= 2

Prevention

Normalize tensor-shaped inputs with reshape at the boundary.
Use pl.DataFrame({"col": arr.tolist()}) when nesting must be preserved.
Document expected ndim on functions that accept raw arrays.

When it happens

Trigger: pl.DataFrame(np.zeros((2, 3, 4))); passing model tensors shaped (batch, seq, features); arrays produced by np.stack of 2D matrices.

Common situations: ML preprocessing pipelines handing batched tensors to polars; image/video data with channel dimensions; forgetting to flatten features before logging experiment metrics into a DataFrame.

Related errors

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