pola-rs/polars · error · ValueError

DataFrame dimensions do not match

Error message

DataFrame dimensions do not match

What it means

After the column check passes, _compare_to_other_df requires equal shapes; a row-count difference makes element-wise comparison undefined and raises ValueError ('DataFrame dimensions do not match'). Polars will not broadcast row-wise between frames, so heights must be identical.

Source

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

    def _comp(self, other: Any, op: ComparisonOperator) -> DataFrame:
        """Compare a DataFrame with another object."""
        if isinstance(other, DataFrame):
            return self._compare_to_other_df(other, op)
        else:
            return self._compare_to_non_df(other, op)

    def _compare_to_other_df(
        self,
        other: DataFrame,
        op: ComparisonOperator,
    ) -> DataFrame:
        """Compare a DataFrame with another DataFrame."""
        if self.columns != other.columns:
            msg = "DataFrame columns do not match"
            raise ValueError(msg)
        if self.shape != other.shape:
            msg = "DataFrame dimensions do not match"
            raise ValueError(msg)

        suffix = "__POLARS_CMP_OTHER"
        other_renamed = other.select(F.all().name.suffix(suffix))
        combined = F.concat([self, other_renamed], how="horizontal", strict=True)

        if op == "eq":
            expr = [F.col(n) == F.col(f"{n}{suffix}") for n in self.columns]
        elif op == "neq":
            expr = [F.col(n) != F.col(f"{n}{suffix}") for n in self.columns]
        elif op == "gt":
            expr = [F.col(n) > F.col(f"{n}{suffix}") for n in self.columns]
        elif op == "lt":
            expr = [F.col(n) < F.col(f"{n}{suffix}") for n in self.columns]
        elif op == "gt_eq":
            expr = [F.col(n) >= F.col(f"{n}{suffix}") for n in self.columns]
        elif op == "lt_eq":
            expr = [F.col(n) <= F.col(f"{n}{suffix}") for n in self.columns]
        else:

View on GitHub (pinned to df599052da)

Solutions

1. Check heights first: df1.height == df2.height, and slice/align deliberately (e.g. both .head(n))
2. For row-order-insensitive comparison use df1.equals(df2.sort(df1.columns)) or join-based comparison
3. In tests use polars.testing.assert_frame_equal with check_row_order=False where appropriate
4. If lengths legitimately differ, compare on keys: df1.join(df2, on='id', how='inner') then compare joined columns

Example fix

# before
result = df1 == df2.head(5)  # df1 has 10 rows -> ValueError

# after
result = df1.head(5) == df2.head(5)

if df.height != other.height:
    raise ValueError(f'row counts differ: {df.height} vs {other.height}; align before comparing')
result = df == other

When it happens

Trigger: df1 == df2 where one frame was filtered, deduplicated, sampled, or aggregated; comparing a full table to a group_by result; comparing against a head()/tail() slice; race where one side was appended to between construction and comparison.

Common situations: Assertion code comparing query output against a golden frame of different length; comparing pre/post-update snapshots; comparing a df to its distinct() version which shrank.

Related errors

• DataFrame columns do not match
• data does not match the number of columns
• dimensions of columns arg ({len(columns)}) must match data d
• height of data ({self.height}) does not match specified heig
• can only set multiple columns with 2D matrix

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