pola-rs/polars · error

cannot use `plot.hist` when Series name is `'count()'`

Error message

cannot use `plot.hist` when Series name is `'count()'`

What it means

Raised by Series.plot.hist (py-polars/src/polars/series/plotting.py:68) when the Series is literally named 'count()'. The histogram hardcodes y="count()" as its Altair aggregation encoding, so a column with that exact name would collide with the aggregation field and produce a broken chart; polars therefore refuses with ValueError up front.

Source

Thrown at py-polars/src/polars/series/plotting.py:68

        .. versionchanged:: 1.6.0
            In prior versions of Polars, HvPlot was the plotting backend. If you would
            like to restore the previous plotting functionality, all you need to do
            is add `import hvplot.polars` at the top of your script and replace
            `df.plot` with `df.hvplot`.

        Parameters
        ----------
        **kwargs
            Additional arguments and keyword arguments passed to Altair.

        Examples
        --------
        >>> s = pl.Series("price", [1, 3, 3, 3, 5, 2, 6, 5, 5, 5, 7])
        >>> s.plot.hist()  # doctest: +SKIP
        """  # noqa: W505
        if self._series_name == "count()":
            msg = "cannot use `plot.hist` when Series name is `'count()'`"
            raise ValueError(msg)
        encodings: Encodings = {
            "x": alt.X(f"{self._series_name}:Q", bin=True),
            "y": "count()",
        }
        return (
            alt.Chart(self._df)
            .mark_bar(tooltip=True)
            .encode(**encodings, **kwargs)
            .interactive()
        )

    def kde(
        self,
        /,
        **kwargs: Unpack[EncodeKwds],
    ) -> alt.Chart:
        """
        Draw kernel density estimate plot.

View on GitHub (pinned to df599052da)

Solutions

1. Rename the Series before plotting: s.rename("price").plot.hist() (rename returns a new Series)
2. Or fix the name upstream where the column was created, so downstream plotting code never sees 'count()'
3. If the name comes from external data, add a rename step in your ingestion pipeline

Example fix

# before
s = pl.Series("count()", [1, 3, 3, 5])
s.plot.hist()  # ValueError

# after
s.rename("price").plot.hist()

PLOT_RESERVED_NAMES = {"count()"}
name = "count()" if s.name in PLOT_RESERVED_NAMES else s.name  # detect
s_safe = s.rename("value") if s.name in PLOT_RESERVED_NAMES else s
s_safe.plot.hist()

try:
    chart = s.plot.hist()
except ValueError as e:
    if "'count()'" in str(e):
        chart = s.rename("value").plot.hist()
    else:
        raise

When it happens

Trigger: pl.Series("count()", [...]).plot.hist(), or plotting a column that was produced by an aggregation and renamed to 'count()' — e.g. df.group_by("a").len().rename({"len": "count()"})["count()"].plot.hist().

Common situations: Chaining value_counts()/group_by output into a histogram plot, or data loaded from sources where the column name happens to be 'count()'. This is a name-collision guard, not a data problem.

Related errors

• cannot use `plot.kde` when Series name is `'density'`
• cannot call `plot.line` when Series name is 'index'
• Cannot call `plot.{attr}` when Series name is 'index'
• Altair has no method 'mark_{attr}'
• altair>=5.4.0 is required for `.plot`

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