What causes "cannot describe a DataFrame that has no columns" in pola-rs/polars?

Guard the call: only describe frames with columns, e.g. `stats = df.describe() if df.width else None`

cannot describe a DataFrame that has no columns

Error message

cannot describe a DataFrame that has no columns

What it means

DataFrame.describe() computes per-column statistics (count, null_count, mean, std, min, percentiles, max), which requires at least one column. A DataFrame with zero columns has nothing to summarize, so polars raises TypeError (note: TypeError, not ValueError) with this message. The check happens up front, before delegating to the lazy describe implementation.

Source

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

        │ ---        ┆ ---      ┆ ---      ┆ ---      ┆ ---  ┆ ---                 ┆ ---      │
        │ str        ┆ f64      ┆ f64      ┆ f64      ┆ str  ┆ str                 ┆ str      │
        ╞════════════╪══════════╪══════════╪══════════╪══════╪═════════════════════╪══════════╡
        │ count      ┆ 3.0      ┆ 2.0      ┆ 3.0      ┆ 3    ┆ 3                   ┆ 3        │
        │ null_count ┆ 0.0      ┆ 1.0      ┆ 0.0      ┆ 0    ┆ 0                   ┆ 0        │
        │ mean       ┆ 2.266667 ┆ 45.0     ┆ 0.666667 ┆ null ┆ 2021-07-02 16:00:00 ┆ 16:07:10 │
        │ std        ┆ 1.101514 ┆ 7.071068 ┆ null     ┆ null ┆ null                ┆ null     │
        │ min        ┆ 1.0      ┆ 40.0     ┆ 0.0      ┆ xx   ┆ 2020-01-01          ┆ 10:20:30 │
        │ 10%        ┆ 1.36     ┆ 41.0     ┆ null     ┆ null ┆ 2020-04-20          ┆ 11:13:34 │
        │ 30%        ┆ 2.08     ┆ 43.0     ┆ null     ┆ null ┆ 2020-11-26          ┆ 12:59:42 │
        │ 50%        ┆ 2.8      ┆ 45.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
        │ 70%        ┆ 2.88     ┆ 47.0     ┆ null     ┆ null ┆ 2022-02-07          ┆ 18:09:34 │
        │ 90%        ┆ 2.96     ┆ 49.0     ┆ null     ┆ null ┆ 2022-09-13          ┆ 21:33:18 │
        │ max        ┆ 3.0      ┆ 50.0     ┆ 1.0      ┆ zz   ┆ 2022-12-31          ┆ 23:15:10 │
        └────────────┴──────────┴──────────┴──────────┴──────┴─────────────────────┴──────────┘
        """  # noqa: W505
        if not self.columns:
            msg = "cannot describe a DataFrame that has no columns"
            raise TypeError(msg)

        return self.lazy().describe(
            percentiles=percentiles, interpolation=interpolation
        )

    def get_column_index(self, name: str) -> int:
        """
        Find the index of a column by name.

        Parameters
        ----------
        name
            Name of the column to find.

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {"foo": [1, 2, 3], "bar": [6, 7, 8], "ham": ["a", "b", "c"]}

View on GitHub (pinned to df599052da)

Solutions

Guard the call: only describe frames with columns, e.g. `stats = df.describe() if df.width else None`
If the frame was not expected to be empty, fix the upstream load (wrong path, empty file, over-filtered select, bad drop list)
For optional preview paths, fall back to logging df.schema or df.shape instead

Example fix

# before
stats = df.describe()  # crashes when df has no columns

# after
stats = df.describe() if df.width else None
print(df.schema if df.width else 'empty frame')

Defensive patterns

Strategy: validation

Validate before calling

if not df.columns:
    raise ValueError(f'cannot describe empty frame with shape {df.shape}')
stats = df.describe()

Prevention

Guard generic EDA loops with `if df.width:` before calling describe
Log df.shape/schema when a load yields zero columns — it usually signals an upstream read problem
In tests, include an empty-frame case for any helper that calls describe

When it happens

Trigger: pl.DataFrame().describe(); df.select([]).describe(); df.drop(df.columns).describe(); calling describe() on a frame whose schema came back empty from a scan/read of an empty file.

Common situations: Generic EDA/reporting loops that call describe() on every loaded table including empty ones; unit tests with empty fixtures; dynamic column selection or drop logic that can reduce width to 0; reading a truncated/empty CSV or Parquet with zero columns.

Related errors

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