pola-rs/polars · error

`orient` must be one of {'col', 'row', None}, got {orient!r}

Error message

`orient` must be one of {'col', 'row', None}, got {orient!r}

What it means

The DataFrame constructor's `orient` parameter only accepts 'col', 'row', or None (auto-detection). Any other value — notably pandas/numpy-flavored spellings like 'columns', 'index', 'C'/'F' — fails this explicit ValueError at the end of orientation dispatch, before the data is processed further.

Source

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

    elif orient == "col":
        column_names, schema_overrides = _unpack_schema(
            schema, schema_overrides=schema_overrides, n_expected=len(data)
        )
        data_series: list[PySeries] = [
            pl.Series(
                column_names[i],
                element,
                dtype=schema_overrides.get(column_names[i]),
                strict=strict,
                nan_to_null=nan_to_null,
            )._s
            for i, element in enumerate(data)
        ]
        return PyDataFrame(data_series)

    else:
        msg = f"`orient` must be one of {{'col', 'row', None}}, got {orient!r}"
        raise ValueError(msg)


def _sequence_of_series_to_pydf(
    first_element: Series,  # noqa: ARG001
    data: Sequence[Any],
    schema: SchemaDefinition | None,
    *,
    schema_overrides: SchemaDict | None,
    strict: bool,
    **kwargs: Any,  # noqa: ARG001
) -> PyDataFrame:
    series_names = [s.name for s in data]
    column_names, schema_overrides = _unpack_schema(
        schema or series_names,
        schema_overrides=schema_overrides,
        n_expected=len(data),
    )
    data_series: list[PySeries] = []

View on GitHub (pinned to df599052da)

Solutions

1. Use `orient="col"` or `orient="row"` — or omit orient entirely and let polars infer it (it warns only when square data is ambiguous)
2. Remember the mapping: 'row' means each inner sequence is a row; 'col' means each inner sequence is a column
3. For pandas interop prefer `pl.from_pandas(df)` instead of translating orient arguments

Example fix

# before
pl.DataFrame([[1, 2], [3, 4]], orient="columns")
# ValueError: `orient` must be one of {'col', 'row', None}, got 'columns'

# after — rows as inner sequences
pl.DataFrame([[1, 2], [3, 4]], orient="row")
# or columns as inner sequences
pl.DataFrame([[1, 3], [2, 4]], orient="col")

import polars as pl

def normalize_orient(orient: str | None) -> str | None:
    mapping = {"columns": "col", "index": "row", "rows": "row", "cols": "col"}
    orient = mapping.get(orient, orient)
    if orient not in {"col", "row", None}:
        raise ValueError(f"invalid orient {orient!r}")
    return orient

from typing import Literal

Orient = Literal["col", "row", None]

def is_valid_orient(value) -> bool:
    return value is None or (isinstance(value, str) and value in {"col", "row"})

try:
    df = pl.DataFrame(data, orient=orient)
except ValueError as e:
    if "orient" not in str(e):
        raise
    raise ValueError(f"orient must be 'col'/'row'/None; got {orient!r} (pandas-style names are not accepted)") from e

When it happens

Trigger: `pl.DataFrame([[1, 2], [3, 4]], orient="columns")`, `orient="rows"`, `orient="index"`, or any string other than 'col'/'row'; passing the value through a variable configured from pandas code.

Common situations: Code mechanically translated from pandas (where 'index'/'columns' are valid); autocomplete choosing the wrong literal; configuration shared between pandas and polars call sites.

Related errors

• Pandas dataframe contains non-unique indices and/or column n
• the given column-schema names do not match the data dictiona
• data does not match the number of columns
• dimensions of columns arg ({len(columns)}) must match data d
• passing Expr objects to the DataFrame constructor is not sup

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