What causes "data does not match the number of columns" in pola-rs/polars?

Make the number of column names equal the number of data columns

pola-rs/polars · error · ShapeError

data does not match the number of columns

Error message

data does not match the number of columns

What it means

Raised by _unpack_schema (as a ShapeError) when explicit column names are provided but their count differs from the number of columns the data actually has. Polars uses n_expected as the arity contract from the input data and fails fast when the supplied names don't line up.

Solutions

Make the number of column names equal the number of data columns
Drop the schema/column_names argument to let Polars name columns column_0, column_1, ...
Verify data width with len(data[0]) for row data or len(data) for column data before constructing

Example fix

// before
pl.DataFrame([[1, 2], [3, 4]], schema=['a', 'b', 'c'])
// after
pl.DataFrame([[1, 2], [3, 4]], schema=['a', 'b'])

Defensive patterns

Strategy: validation

Validate before calling

names = schema if isinstance(schema, list) else list(schema or {})
assert len(names) == len(data[0]), f'{len(names)} names vs {len(data[0])} columns'

Try / catch

try:
    df = pl.DataFrame(rows, schema=names)
except pl.exceptions.ShapeError as e:
    if 'does not match the number of columns' in str(e):
        df = pl.DataFrame(rows)
    else:
        raise

Prevention

Build column-name lists from the data shape, not by hand
Add an assertion comparing len(schema) to data width before constructing
When width changes, search call sites that hardcode schema

When it happens

Trigger: pl.DataFrame([[1,2],[3,4]], schema=['a','b','c']) — three names for two columns; sequence-of-sequences, sequence-of-series, or sequence-of-dicts input with a schema list whose length differs from the data width.

Common situations: Adding a column to the data without updating the schema list, copying a constructor call from another snippet and forgetting to adjust column names, row- vs column-oriented confusion about expected width.

Related errors

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

Appendix: source

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

        return columns, schema_overrides

    # determine column names from schema
    if isinstance(schema, Mapping):
        column_names: list[str] = list(schema)
        schema = list(schema.items())
    else:
        column_names = []
        for i, col in enumerate(schema):
            if isinstance(col, str):
                unnamed = not col and col not in schema_overrides
                col = f"column_{i}" if unnamed else col
            else:
                col = col[0]
            column_names.append(col)

    if n_expected is not None and len(column_names) != n_expected:
        msg = "data does not match the number of columns"
        raise ShapeError(msg)

    # determine column dtypes from schema and lookup_names
    lookup: dict[str, str] | None = (
        {
            col: name
            for col, name in zip_longest(column_names, lookup_names)
            if name is not None
        }
        if lookup_names
        else None
    )

    column_dtypes: dict[str, PolarsDataType] = {}
    for col in schema:
        if isinstance(col, str):
            continue

        name, dtype = col

View on GitHub (pinned to fe841f959e)