pola-rs/polars · error · ValueError

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

Error message

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

What it means

Series.plot.hist() builds an Altair chart that encodes the y-axis as the literal Vega-Lite aggregate 'count()'. If the Series itself is named 'count()', the generated encoding collides (duplicate/conflicting field name), so polars raises ValueError upfront.

Solutions

1. Rename the Series first: s.rename("value").plot.hist()
2. Use s.alias("frequency") before plotting
3. Set the name at construction: pl.Series("price", values).plot.hist()

Example fix

// before
s.rename("count()").plot.hist()
// after
s.rename("frequency").plot.hist()

if s.name == "count()":
    s = s.rename("frequency")
s.plot.hist()

try:
    chart = s.plot.hist()
except ValueError:
    chart = s.rename("frequency").plot.hist()

When it happens

Trigger: Calling s.plot.hist() on a Series whose name is exactly 'count()' — typically a Series produced by a group_by().len()/count() aggregation that kept the default 'count' name variant or was explicitly named 'count()'.

Common situations: Chaining plotting directly onto a counting aggregation like df.group_by("x").len().get_column("len") after renaming to 'count()'; round-tripping through systems that emit Vega-Lite-style aggregate names.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

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

Appendix: 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 fe841f959e)