pola-rs/polars · error · ValueError

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

Error message

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

What it means

Raised by dict_to_pydf when a schema (mapping of column names to dtypes) is supplied alongside a data dict, but the data dict contains keys not present in the schema. Polars validates that every data key exists in the schema before reordering data to schema order, raising ValueError on any mismatch.

Solutions

Ensure every key in the data dict appears in the schema mapping
Omit the schema parameter and let Polars infer dtypes
Print/set(data) and set(schema) and diff them to find the mismatch

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

missing = set(data) - set(schema or {})
if missing:
    raise ValueError(f'schema is missing data columns: {missing}')

Type guard

def schema_matches_data(data: dict, schema: dict | None) -> bool:
    return schema is None or set(data) <= set(schema)

Try / catch

try:
    df = pl.DataFrame(data, schema=schema)
except ValueError as e:
    if 'column-schema names do not match' in str(e):
        df = pl.DataFrame(data)  # fall back to inferred schema
    else:
        raise

Prevention

Derive the schema from the data keys programmatically
Diff set(data) vs set(schema) in a debug assertion
Avoid hand-maintained schema literals for wide dicts

When it happens

Trigger: Calling pl.DataFrame({'a': [1], 'b': [2]}, schema={'a': pl.Int64, 'c': pl.Int64}) — a schema key that doesn't exist in the data dict; also via pl.from_dict or sequence_to_pydf with dict data and a mismatched schema.

Common situations: Typos in schema column names, schema built from a stale list of columns after upstream data changed, generating schema programmatically and missing a renamed column.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: 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 fe841f959e)