{"record":{"id":"da82a22e0f65b44d","repo":"pola-rs/polars","slug":"data-does-not-match-the-number-of-columns","errorCode":null,"errorMessage":"data does not match the number of columns","messagePattern":"data does not match the number of columns","errorType":"exception","errorClass":"ShapeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/construction/dataframe.py","lineNumber":226,"sourceCode":"        return columns, schema_overrides\n\n    # determine column names from schema\n    if isinstance(schema, Mapping):\n        column_names: list[str] = list(schema)\n        schema = list(schema.items())\n    else:\n        column_names = []\n        for i, col in enumerate(schema):\n            if isinstance(col, str):\n                unnamed = not col and col not in schema_overrides\n                col = f\"column_{i}\" if unnamed else col\n            else:\n                col = col[0]\n            column_names.append(col)\n\n    if n_expected is not None and len(column_names) != n_expected:\n        msg = \"data does not match the number of columns\"\n        raise ShapeError(msg)\n\n    # determine column dtypes from schema and lookup_names\n    lookup: dict[str, str] | None = (\n        {\n            col: name\n            for col, name in zip_longest(column_names, lookup_names)\n            if name is not None\n        }\n        if lookup_names\n        else None\n    )\n\n    column_dtypes: dict[str, PolarsDataType] = {}\n    for col in schema:\n        if isinstance(col, str):\n            continue\n\n        name, dtype = col","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_utils/construction/dataframe.py#L208-L244","documentation":"While unpacking a `schema` argument for DataFrame construction, polars derives column names and compares their count against n_expected — the number of columns the data actually provides. A mismatch raises ShapeError (from polars.exceptions), covering sequence/list-style schemas where the number of names disagrees with the data's column count.","triggerScenarios":"`pl.DataFrame([[1, 2], [3, 4]], schema=[\"a\"])` (2 data columns, 1 schema name), or `pl.DataFrame(data_with_3_columns, schema=[\"a\", \"b\"])` — any positional schema whose length differs from the number of columns in the data.","commonSituations":"Hardcoded name lists not updated after upstream added/removed a field; ragged row data producing an unexpected column count; schemas written for one dataset reused on another with a different width.","solutions":["Make the lengths agree — one name per data column","Omit the schema and rename afterwards: `df.rename({\"old\": \"new\"})` or `df.columns = [...]`","Generate names programmatically: `schema=[f\"column_{i}\" for i in range(n_cols)]`","Catch `polars.exceptions.ShapeError` at the boundary to re-raise an app-level message with the data's actual width"],"exampleFix":"# before\npl.DataFrame([[1, 2], [3, 4]], schema=[\"a\"])\n# ShapeError: data does not match the number of columns\n\n# after\npl.DataFrame([[1, 2], [3, 4]], schema=[\"a\", \"b\"])","handlingStrategy":"validation","validationCode":"import polars as pl\n\ndef width(rows: list[list]) -> int:\n    return len(rows[0]) if rows else 0\n\nnames = [\"a\", \"b\"]\nrows = [[1, 2], [3, 4]]\nassert len(names) == width(rows), f\"schema has {len(names)} names but data has {width(rows)} columns\"\ndf = pl.DataFrame(rows, schema=names, orient=\"row\")","typeGuard":"def schema_matches_width(schema: list[str] | None, n_cols: int) -> bool:\n    \"\"\"True if schema length equals the data's column count (or schema is None).\"\"\"\n    return schema is None or len(schema) == n_cols","tryCatchPattern":"from polars.exceptions import ShapeError\n\ntry:\n    df = pl.DataFrame(rows, schema=names)\nexcept ShapeError as e:\n    raise ValueError(f\"input width changed: expected {len(names)} columns, got {len(rows[0]) if rows else 0}\") from e","preventionTips":["Derive column counts from the data instead of hardcoding name lists","Validate incoming rows for consistent width before construction (polars also errors on ragged rows)","Catch polars.exceptions.ShapeError at data-ingestion boundaries to surface app-level diagnostics"],"tags":["dataframe-construction","schema","shape-mismatch","columns"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}