{"record":{"id":"35685314e0d4073b","repo":"pola-rs/polars","slug":"cannot-create-dataframe-from-array-with-more-than","errorCode":null,"errorMessage":"cannot create DataFrame from array with more than two dimensions; shape = {shape}","messagePattern":"cannot create DataFrame from array with more than two dimensions; shape = (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/construction/dataframe.py","lineNumber":1287,"sourceCode":"                    orient = \"col\"\n                    n_columns = n_schema_cols\n                else:\n                    orient = \"row\"\n                    n_columns = shape[1]\n\n            elif orient == \"row\":\n                n_columns = shape[1]\n            elif orient == \"col\":\n                n_columns = shape[0]\n            else:\n                msg = f\"`orient` must be one of {{'col', 'row', None}}, got {orient!r}\"\n                raise ValueError(msg)\n        else:\n            if shape == ():\n                msg = \"cannot create DataFrame from zero-dimensional array\"\n            else:\n                msg = f\"cannot create DataFrame from array with more than two dimensions; shape = {shape}\"\n            raise ValueError(msg)\n\n    if schema is not None and len(schema) != n_columns:\n        if (n_schema_cols := len(schema)) != 1:\n            msg = f\"dimensions of `schema` ({n_schema_cols}) must match data dimensions ({n_columns})\"\n            raise ValueError(msg)\n        n_columns = n_schema_cols\n\n    column_names, schema_overrides = _unpack_schema(\n        schema, schema_overrides=schema_overrides, n_expected=n_columns\n    )\n\n    # Convert data to series\n    if structured_array:\n        data_series = [\n            pl.Series(\n                name=series_name,\n                values=data[record_name],\n                dtype=schema_overrides.get(record_name),","sourceCodeStart":1269,"sourceCodeEnd":1305,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/_utils/construction/dataframe.py#L1269-L1305","documentation":"Polars DataFrames are tabular (2-D) structures. `numpy_to_pydf` refuses numpy arrays with more than two dimensions because there is no unambiguous way to map a 3-D+ array onto named columns. It raises ValueError with the offending shape.","triggerScenarios":"Calling pl.DataFrame(arr), pl.from_numpy(arr) or pl.from_torch(tensor) where arr.ndim > 2, e.g. a (n, h, w) image batch or a (batch, seq, feature) tensor.","commonSituations":"Passing image stacks, tensor batches from PyTorch/TF, or reshaped ML feature arrays directly into pl.DataFrame / pl.from_numpy without flattening.","solutions":["Reshape the array to two dimensions before construction, e.g. arr.reshape(arr.shape[0], -1).","Explode the extra dimensions into multiple columns explicitly (one per inner feature).","Store the extra dimension in a list/Array column: pl.DataFrame({'v': list(arr)}) with pl.Array/pl.List dtype."],"exampleFix":"// before\npl.from_numpy(batch_images)  # shape (100, 28, 28)\n// after\narr = batch_images.reshape(batch_images.shape[0], -1)\ndf = pl.from_numpy(arr, schema={f'px{i}': pl.Float32 for i in range(arr.shape[1])})","handlingStrategy":"validation","validationCode":"if arr.ndim > 2:\n    raise ValueError(f'expected <=2-D array, got shape {arr.shape}')","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.from_numpy(arr)\nexcept ValueError as e:\n    if 'more than two dimensions' in str(e):\n        arr = arr.reshape(arr.shape[0], -1)\n        df = pl.from_numpy(arr)\n    else:\n        raise","preventionTips":["Assert arr.ndim <= 2 at the boundary where arrays enter DataFrame construction.","Flatten image/tensor batches at the source with reshape.","Use pl.Array or pl.List columns to preserve extra dimensions."],"tags":["polars","dataframe","numpy","shape"],"backgroundTag":"tensor-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"}