pola-rs/polars · error

`orient` must be one of

Error message

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

What it means

Raised by numpy_to_pydf when a 2-D numpy array is passed with an `orient` value other than 'col', 'row', or None. Orient decides whether shape[1] (row orientation) or shape[0] (column orientation) is the column count, and any other string is rejected with ValueError.

Solutions

1. Pass orient='col', orient='row', or leave it as None
2. Normalize legacy values before the call, e.g. {'columns':'col','index':'row'}.get(orient)
3. Drop orient and reshape the array so the desired orientation is implicit (columns last)

Example fix

// before
pl.from_numpy(arr, orient='columns')
// after
pl.from_numpy(arr, orient='col')

assert orient in ('col', 'row', None), f'orient must be col|row|None, got {orient!r}'

def valid_orient(orient: str | None) -> bool:
    return orient in ('col', 'row', None)

try:
    df = pl.from_numpy(arr, orient=orient)
except ValueError as e:
    if 'orient' in str(e) and 'must be one of' in str(e):
        df = pl.from_numpy(arr)  # default orientation
    else:
        raise

When it happens

Trigger: pl.from_numpy(arr, orient='columns') or pl.DataFrame(np_arr, orient='horizontal') — non-canonical orient strings passed via from_numpy, from_torch, or __init__.

Common situations: Using pandas-style orient vocabulary ('index'/'columns'), typos ('cols'), config-driven orient values not normalized before the call.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• `orient` must be one of
• arr.dot query vector must be one-dimensional
• cannot convert DataFrame to
• cannot convert List column
• cannot parse numpy data type

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

Appendix: source

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

                # we check the flags to establish row/column major order
                n_schema_cols = len(schema)
                if n_schema_cols == shape[0] and n_schema_cols != shape[1]:
                    orient = "col"
                    n_columns = shape[0]
                elif data.flags["F_CONTIGUOUS"] and shape[0] == shape[1]:
                    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

View on GitHub (pinned to fe841f959e)