pola-rs/polars · error

cannot call `plot.line` when Series name is 'index'

Error message

cannot call `plot.line` when Series name is 'index'

What it means

Raised by Series.plot.line (py-polars/src/polars/series/plotting.py:158) when the Series is named 'index'. The line plot uses with_row_index() to synthesize an x-axis column named 'index'; a Series already named 'index' would make x and y reference the same field, so polars refuses with ValueError.

Source

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

        .. 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 keyword arguments passed to Altair.

        Examples
        --------
        >>> 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}'"

View on GitHub (pinned to df599052da)

Solutions

1. Rename before plotting: s.rename("idx").plot.line()
2. Rename the column in the DataFrame: df = df.rename({"index": "row"}) then df["row"].plot.line()
3. If you want the index on the x-axis of a differently named column, that already works: df["value"].plot.line()

Example fix

# before
df["index"].plot.line()  # ValueError

# after
df["index"].rename("row").plot.line()

s_safe = s.rename("row") if s.name == "index" else s
s_safe.plot.line()

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

When it happens

Trigger: pl.Series("index", [...]).plot.line(), or df["index"].plot.line() on any DataFrame column literally named 'index' (e.g. after reset_index-style operations ported from pandas, or CSV/database columns named 'index').

Common situations: Migrating pandas workflows where 'index' is a common column name; plotting a row-number column; data from sources that use 'index' as a field. Affects plot.line and every mark_* chart (see the __getattr__ variant, error 510).

Related errors

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