the given column-schema names do not match the data dictiona

Error message

the given column-schema names do not match the data dictionary

What it means

In the dict-of-data constructor path (dict_to_pydf), when `schema` is supplied as a Mapping (name -> dtype), every key of the data dictionary must appear in the schema: the schema Mapping is authoritative for column order and dtypes, so extra data keys are an error rather than silently dropped. Any data column missing from the schema Mapping raises this ValueError.

Source

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

    )

_MIN_NUMPY_SIZE_FOR_MULTITHREADING = 1000


def dict_to_pydf(
    data: Mapping[str, ArrayLike | NonNestedLiteral | None],
    schema: SchemaDefinition | None = None,
    *,
    schema_overrides: SchemaDict | None = None,
    strict: bool = True,
    nan_to_null: bool = False,
    allow_multithreaded: bool = True,
) -> PyDataFrame:
    """Construct a PyDataFrame from a dictionary of sequences."""
    if isinstance(schema, Mapping) and data:
        if not all((col in schema) for col in data):
            msg = "the given column-schema names do not match the data dictionary"
            raise ValueError(msg)
        data = {col: data[col] for col in schema}

    column_names, schema_overrides = _unpack_schema(
        schema, lookup_names=data.keys(), schema_overrides=schema_overrides
    )
    if not column_names:
        column_names = list(data)

    if data and _NUMPY_AVAILABLE:
        # if there are 3 or more numpy arrays of sufficient size, we multi-thread:
        count_numpy = sum(
            int(
                allow_multithreaded
                and _check_for_numpy(val)
                and isinstance(val, np.ndarray)
                and len(val) > _MIN_NUMPY_SIZE_FOR_MULTITHREADING
                # integers and non-nan floats are zero-copy
                and nan_to_null

View on GitHub (pinned to df599052da)

Solutions

Use `schema_overrides={"a": pl.Int64}` when you only want to set dtypes for some columns — partial input is allowed there
Or include every data column in the schema Mapping: `schema={"a": pl.Int64, "b": pl.Int64}`
Or derive the schema from the data keys: `schema={k: pl.Int64 for k in data}`
Validate first: `assert set(data) <= set(schema or {})`

Example fix

# before
pl.DataFrame({"a": [1, 2], "b": [3, 4]}, schema={"a": pl.Int64})
# ValueError: the given column-schema names do not match the data dictionary

# after (partial dtype override -> use schema_overrides)
pl.DataFrame({"a": [1, 2], "b": [3, 4]}, schema_overrides={"a": pl.Int64})

# after (full schema -> include every column)
pl.DataFrame({"a": [1, 2], "b": [3, 4]}, schema={"a": pl.Int64, "b": pl.Int64})

Defensive patterns

Strategy: validation

Validate before calling

import polars as pl
from collections.abc import Mapping

def safe_from_dict(data: dict, schema=None, **kw) -> pl.DataFrame:
    if isinstance(schema, Mapping):
        extra = set(data) - set(schema)
        if extra:
            raise ValueError(f"data columns missing from schema: {sorted(extra)}")
    return pl.DataFrame(data, schema=schema, **kw)

Type guard

from collections.abc import Mapping

def schema_covers_data(data: Mapping, schema: Mapping | None) -> bool:
    """True if schema is None (no restriction) or contains every data key."""
    return schema is None or set(data).issubset(schema)

Try / catch

try:
    df = pl.DataFrame(data, schema=schema)
except ValueError as e:
    if "column-schema names" not in str(e):
        raise
    # fall back to overrides-only semantics
    df = pl.DataFrame(data, schema_overrides={k: v for k, v in schema.items() if k in data})

Prevention

Use schema_overrides (partial) instead of schema (complete) when you only mean to set some dtypes
Assert `set(data) <= set(schema)` when schema dicts are config-driven and data is external
Generate schema from data keys when order/dtypes allow: {k: dtype for k in data}

When it happens

Trigger: `pl.DataFrame({"a": [1], "b": [2]}, schema={"a": pl.Int64})` — 'b' is present in data but absent from the schema Mapping. Also dynamic data whose keys drift while the schema dict stays static (config-driven pipelines).

Common situations: A fixed schema dict that no longer matches upstream data after a column was added; intending to override dtypes for only some columns (that is `schema_overrides`, not `schema`); renaming columns via schema while forgetting the remaining keys.

Related errors

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