pola-rs/polars · error

Cannot call `plot.{attr}` when Series name is 'index'

Error message

Cannot call `plot.{attr}` when Series name is 'index'

What it means

Raised by SeriesPlot.__getattr__ (py-polars/src/polars/series/plotting.py:170) for ANY dynamically-dispatched chart method (s.plot.bar, s.plot.point, s.plot.area, ...) when the Series is named 'index'. Like plot.line, these charts synthesize the x-axis via with_row_index() (column 'index'), so a Series named 'index' collides with the x encoding. Only plot.hist, plot.kde and plot.line have their own messages; everything else goes through this generic one.

Source

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

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

    def __getattr__(self, attr: str) -> Callable[..., alt.Chart]:
        if self._series_name == "index":
            msg = f"Cannot call `plot.{attr}` when Series name is 'index'"
            raise ValueError(msg)
        if attr == "scatter":
            # alias `scatter` to `point` because of how common it is
            attr = "point"
        method = getattr(alt.Chart(self._df.with_row_index()), f"mark_{attr}", None)
        if method is None:
            msg = f"Altair has no method 'mark_{attr}'"
            raise AttributeError(msg)
        encodings: Encodings = {"x": "index", "y": self._series_name}

        accepts_tooltip_argument = "tooltip" in {
            value.name for value in inspect.signature(method).parameters.values()
        }
        if accepts_tooltip_argument:

            def func(**kwargs: EncodeKwds) -> alt.Chart:
                return method(tooltip=True).encode(**encodings, **kwargs).interactive()
        else:

View on GitHub (pinned to df599052da)

Solutions

1. Rename the Series before plotting: s.rename("row").plot.bar()
2. Rename the column upstream: df = df.rename({"index": "row_num"})
3. Treat 'index' as a reserved name for charting code paths; add a rename step in your plotting helper

Example fix

# before
pl.Series("index", [1, 2, 3]).plot.bar()  # ValueError

# after
pl.Series("index", [1, 2, 3]).rename("row").plot.bar()

def plot_series(s, mark="bar", **kw):
    if s.name == "index":
        s = s.rename("row")
    return getattr(s.plot, mark)(**kw)

try:
    chart = s.plot.point()
except ValueError as e:
    if "Series name is 'index'" in str(e):
        chart = s.rename("row").plot.point()
    else:
        raise

When it happens

Trigger: pl.Series("index", [...]).plot.bar(), df["index"].plot.point(), df["index"].plot.scatter() (scatter is aliased to point first, then still fails the name check).

Common situations: Same as the line variant: pandas-style 'index' column names, plotting row-number series. Developers hit this via any mark_* method, so the message names plot.<attr> with the actual attribute used.

Related errors

• cannot use `plot.hist` when Series name is `'count()'`
• cannot use `plot.kde` when Series name is `'density'`
• cannot call `plot.line` 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/334030ec14675f5b. Report an issue: GitHub.