{"record":{"id":"9b0222d32bc99963","repo":"pola-rs/polars","slug":"the-given-column-schema-names-do-not-match-the-dat","errorCode":null,"errorMessage":"the given column-schema names do not match the data dictionary","messagePattern":"the given column-schema names do not match the data dictionary","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/construction/dataframe.py","lineNumber":92,"sourceCode":"    )\n\n_MIN_NUMPY_SIZE_FOR_MULTITHREADING = 1000\n\n\ndef dict_to_pydf(\n    data: Mapping[str, ArrayLike | NonNestedLiteral | None],\n    schema: SchemaDefinition | None = None,\n    *,\n    schema_overrides: SchemaDict | None = None,\n    strict: bool = True,\n    nan_to_null: bool = False,\n    allow_multithreaded: bool = True,\n) -> PyDataFrame:\n    \"\"\"Construct a PyDataFrame from a dictionary of sequences.\"\"\"\n    if isinstance(schema, Mapping) and data:\n        if not all((col in schema) for col in data):\n            msg = \"the given column-schema names do not match the data dictionary\"\n            raise ValueError(msg)\n        data = {col: data[col] for col in schema}\n\n    column_names, schema_overrides = _unpack_schema(\n        schema, lookup_names=data.keys(), schema_overrides=schema_overrides\n    )\n    if not column_names:\n        column_names = list(data)\n\n    if data and _NUMPY_AVAILABLE:\n        # if there are 3 or more numpy arrays of sufficient size, we multi-thread:\n        count_numpy = sum(\n            int(\n                allow_multithreaded\n                and _check_for_numpy(val)\n                and isinstance(val, np.ndarray)\n                and len(val) > _MIN_NUMPY_SIZE_FOR_MULTITHREADING\n                # integers and non-nan floats are zero-copy\n                and nan_to_null","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_utils/construction/dataframe.py#L74-L110","documentation":"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.","triggerScenarios":"`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).","commonSituations":"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.","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 {})`"],"exampleFix":"# before\npl.DataFrame({\"a\": [1, 2], \"b\": [3, 4]}, schema={\"a\": pl.Int64})\n# ValueError: the given column-schema names do not match the data dictionary\n\n# after (partial dtype override -> use schema_overrides)\npl.DataFrame({\"a\": [1, 2], \"b\": [3, 4]}, schema_overrides={\"a\": pl.Int64})\n\n# after (full schema -> include every column)\npl.DataFrame({\"a\": [1, 2], \"b\": [3, 4]}, schema={\"a\": pl.Int64, \"b\": pl.Int64})","handlingStrategy":"validation","validationCode":"import polars as pl\nfrom collections.abc import Mapping\n\ndef safe_from_dict(data: dict, schema=None, **kw) -> pl.DataFrame:\n    if isinstance(schema, Mapping):\n        extra = set(data) - set(schema)\n        if extra:\n            raise ValueError(f\"data columns missing from schema: {sorted(extra)}\")\n    return pl.DataFrame(data, schema=schema, **kw)","typeGuard":"from collections.abc import Mapping\n\ndef schema_covers_data(data: Mapping, schema: Mapping | None) -> bool:\n    \"\"\"True if schema is None (no restriction) or contains every data key.\"\"\"\n    return schema is None or set(data).issubset(schema)","tryCatchPattern":"try:\n    df = pl.DataFrame(data, schema=schema)\nexcept ValueError as e:\n    if \"column-schema names\" not in str(e):\n        raise\n    # fall back to overrides-only semantics\n    df = pl.DataFrame(data, schema_overrides={k: v for k, v in schema.items() if k in data})","preventionTips":["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}"],"tags":["dataframe-construction","schema","validation","dict-input"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}