dimensions of columns arg must match data dimensions

Error message

dimensions of columns arg must match data dimensions

What it means

Raised by arrow_to_pydf when the supplied `columns` (or schema) names cannot be applied to the arrow table because the counts differ, surfacing as ValueError chained from pa.ArrowInvalid during rename_columns. The rename fails because the number of new names doesn't equal the number of arrow columns.

Solutions

Supply exactly as many column names as the arrow table has columns (data.schema.names)
Omit the schema/column_names argument to keep the arrow names
Inspect data.schema.names and align your names list to it, including index columns

Example fix

// before
pl.from_arrow(table, schema=['a', 'b'])  # table has 3 columns
// after
pl.from_arrow(table, schema=['a', 'b', 'c'])

Defensive patterns

Strategy: validation

Validate before calling

names = schema if isinstance(schema, list) else None
assert names is None or len(names) == table.num_columns, \
    f'{len(names)} names for {table.num_columns} arrow columns'

Try / catch

try:
    df = pl.from_arrow(table, schema=schema)
except ValueError as e:
    if 'must match data dimensions' in str(e):
        df = pl.from_arrow(table)
    else:
        raise

Prevention

Compare your name list against table.schema.names before converting
Remember index columns add to the arrow table width
Let arrow names pass through when only dtypes matter

When it happens

Trigger: pl.from_arrow(pa.table({...}), schema=['a','b']) where the schema has a different number of names than the table's columns; also hit when pandas_to_pydf routes through arrow with mismatched names.

Common situations: Providing names only for a subset of arrow columns, forgetting that index columns become extra columns in the arrow table, stale schema lists after the source table gained/lost columns.

Related errors

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

Appendix: source

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

def arrow_to_pydf(
    data: pa.Table | pa.RecordBatch,
    schema: SchemaDefinition | None = None,
    *,
    schema_overrides: SchemaDict | None = None,
    strict: bool = True,
    rechunk: bool = True,
) -> PyDataFrame:
    """Construct a PyDataFrame from an Arrow Table or RecordBatch."""
    column_names, schema_overrides = _unpack_schema(
        (schema or data.schema.names), schema_overrides=schema_overrides
    )
    try:
        if column_names != data.schema.names:
            data = data.rename_columns(column_names)
    except pa.ArrowInvalid as e:
        msg = "dimensions of columns arg must match data dimensions"
        raise ValueError(msg) from e

    batches: list[pa.RecordBatch]
    if isinstance(data, pa.RecordBatch):
        batches = [data]
    elif data.num_columns == 0:
        return PyDataFrame.empty_with_height(data.num_rows)
    else:
        batches = data.to_batches()

    # supply the arrow schema so the metadata is intact
    pydf = PyDataFrame.from_arrow_record_batches(batches, data.schema)

    if rechunk:
        pydf = pydf.rechunk()

    if schema_overrides is not None:
        pydf = _post_apply_columns(
            pydf,

View on GitHub (pinned to fe841f959e)