{"record":{"id":"fabf0e368ee4ac68","repo":"pola-rs/polars","slug":"dimensions-of-columns-arg-len-columns-must-ma","errorCode":null,"errorMessage":"dimensions of columns arg ({len(columns)}) must match data dimensions ({len(data)})","messagePattern":"dimensions of columns arg \\((.+?)\\) must match data dimensions \\((.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/construction/dataframe.py","lineNumber":272,"sourceCode":"        column_dtypes.update(schema_overrides)\n\n    return column_names, column_dtypes\n\n\ndef _handle_columns_arg(\n    data: list[PySeries],\n    columns: Sequence[str] | None = None,\n    *,\n    from_dict: bool = False,\n) -> list[PySeries]:\n    \"\"\"Rename data according to columns argument.\"\"\"\n    if columns is None:\n        return data\n    elif not data:\n        return [pl.Series(name=c)._s for c in columns]\n    elif len(data) != len(columns):\n        msg = f\"dimensions of columns arg ({len(columns)}) must match data dimensions ({len(data)})\"\n        raise ValueError(msg)\n\n    if from_dict:\n        series_map = {s.name(): s for s in data}\n        if all((col in series_map) for col in columns):\n            return [series_map[col] for col in columns]\n\n    for i, c in enumerate(columns):\n        if c != data[i].name():\n            data[i] = data[i].clone()\n            data[i].rename(c)\n\n    return data\n\n\ndef _post_apply_columns(\n    pydf: PyDataFrame,\n    columns: SchemaDefinition | None,\n    structs: dict[str, Struct] | None = None,","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/_utils/construction/dataframe.py#L254-L290","documentation":"Raised by _handle_columns_arg when a `columns` list is passed but its length differs from the number of columns in the constructed data. After empty-data special-casing, Polars requires an exact 1:1 correspondence between replacement names and data columns.","triggerScenarios":"pl.DataFrame({'a':[1],'b':[2]}, columns=['x','y','z']); also numpy_to_pydf, series_to_pydf, dataframe_to_pydf, and sequence-based constructors called with a columns list of the wrong length.","commonSituations":"Hardcoded column-name list not updated after data shape changes, combining multiple data sources into one constructor call, off-by-one from including/excluding an index column name.","solutions":["Pass a columns list with exactly as many names as data columns","Use schema={'name': dtype} instead if you also need dtypes","Compute columns dynamically from the data, e.g. columns=[f'c{i}' for i in range(len(data))]"],"exampleFix":"// before\npl.DataFrame({'a': [1], 'b': [2]}, columns=['x', 'y', 'z'])\n// after\npl.DataFrame({'a': [1], 'b': [2]}, columns=['x', 'y'])","handlingStrategy":"validation","validationCode":"if columns is not None and data is not None and len(data) != len(columns):\n    raise ValueError('columns names count must equal number of data columns')","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.DataFrame(data, columns=columns)\nexcept ValueError as e:\n    if 'must match data dimensions' in str(e):\n        df = pl.DataFrame(data)\n    else:\n        raise","preventionTips":["Generate default names from data: [f'c{i}' for i in range(len(data))]","Prefer schema= over columns= when dtypes are also needed","Never keep a stale literal columns list next to changing data"],"tags":["python","polars","dataframe-construction","shape"],"backgroundTag":"shape-mismatch","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}