cannot create DataFrame from array with more than two…

Error message

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

What it means

Polars DataFrames are tabular (2-D) structures. `numpy_to_pydf` refuses numpy arrays with more than two dimensions because there is no unambiguous way to map a 3-D+ array onto named columns. It raises ValueError with the offending shape.

Solutions

Reshape the array to two dimensions before construction, e.g. arr.reshape(arr.shape[0], -1).
Explode the extra dimensions into multiple columns explicitly (one per inner feature).
Store the extra dimension in a list/Array column: pl.DataFrame({'v': list(arr)}) with pl.Array/pl.List dtype.

Example fix

// before
pl.from_numpy(batch_images)  # shape (100, 28, 28)
// after
arr = batch_images.reshape(batch_images.shape[0], -1)
df = pl.from_numpy(arr, schema={f'px{i}': pl.Float32 for i in range(arr.shape[1])})

Defensive patterns

Strategy: validation

Validate before calling

if arr.ndim > 2:
    raise ValueError(f'expected <=2-D array, got shape {arr.shape}')

Try / catch

try:
    df = pl.from_numpy(arr)
except ValueError as e:
    if 'more than two dimensions' in str(e):
        arr = arr.reshape(arr.shape[0], -1)
        df = pl.from_numpy(arr)
    else:
        raise

Prevention

Assert arr.ndim <= 2 at the boundary where arrays enter DataFrame construction.
Flatten image/tensor batches at the source with reshape.
Use pl.Array or pl.List columns to preserve extra dimensions.

When it happens

Trigger: Calling pl.DataFrame(arr), pl.from_numpy(arr) or pl.from_torch(tensor) where arr.ndim > 2, e.g. a (n, h, w) image batch or a (batch, seq, feature) tensor.

Common situations: Passing image stacks, tensor batches from PyTorch/TF, or reshaped ML feature arrays directly into pl.DataFrame / pl.from_numpy without flattening.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

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

Appendix: source

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

                    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 fe841f959e)