pola-rs/polars · error · ShapeError

height of data ({self.height}) does not match specified heig

Error message

height of data ({self.height}) does not match specified height ({height})

What it means

After successful construction, the polars DataFrame constructor validates the optional `height` hint against the actual row count and raises polars.exceptions.ShapeError on mismatch. The parameter exists so internal fast paths (e.g. dict/records construction) can assert expected sizes cheaply; when supplied explicitly it must equal data's height.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:496

        elif is_pycapsule(data):
            self._df = pycapsule_to_frame(
                data,
                schema=schema,
                schema_overrides=schema_overrides,
            )._df
        else:
            msg = (
                f"DataFrame constructor called with unsupported type {type(data).__name__!r}"
                " for the `data` parameter"
            )
            raise TypeError(msg)

        if height is not None and self.height != height:
            from polars.exceptions import ShapeError

            msg = f"height of data ({self.height}) does not match specified height ({height})"
            raise ShapeError(msg)

    @classmethod
    def deserialize(
        cls,
        source: str | bytes | Path | IOBase,
        *,
        format: SerializationFormat = "binary",
    ) -> DataFrame:
        """
        Read a serialized DataFrame from a file.

        Parameters
        ----------
        source
            Path to a file or a file-like object (by file-like object, we refer to
            objects that have a `read()` method, such as a file handler (e.g.
            via builtin `open` function) or `BytesIO`).
        format

View on GitHub (pinned to df599052da)

Solutions

Omit the height parameter entirely; polars derives it from the data
If you pass it, compute it from the same data: height=len(rows)
If you need fixed-size output, pad or slice the data explicitly before constructing

Example fix

# before
df = pl.DataFrame({'a': [1, 2, 3]}, height=5)

# after
df = pl.DataFrame({'a': [1, 2, 3]})

Defensive patterns

Strategy: validation

Validate before calling

if height is not None and hasattr(data, '__len__') and len(data) != height:
    raise ValueError(f'expected {height} rows, data has {len(data)}; refusing to construct')

Prevention

Treat DataFrame(height=...) as an internal assertion, not a user knob; simply omit it
When replaying cached schema metadata, recompute height from the current data
Use polars.testing.assert_frame_equal for size assertions in tests instead

When it happens

Trigger: pl.DataFrame(data, height=5) where data has any other number of rows; explicitly passing height alongside from_records/from_dict style inputs; calling internal helpers that thread a height hint computed from a different (stale) dataset.

Common situations: Users copying constructor internals or using height as a 'truncate/pad to length' knob (it is not); stale height constants after the source data changed size; framework code that caches schema+height and replays them against refreshed data.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/c710dff32d209e37. Report an issue: GitHub.