pola-rs/polars · error · ValueError

Cannot call `plot. ` when Series name is 'index

Error message

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

What it means

SeriesPlot.__getattr__ dispatches unknown attributes to Altair mark_* methods. Before doing so it rejects ANY plot method when the Series is named 'index', because the generated x-encoding field 'index' (from with_row_index()) would collide with the series name — raising ValueError.

Solutions

1. Rename the Series before plotting: s.rename("value").plot.scatter()
2. Use s.alias(...) to change the name in an expression chain
3. Build the Altair chart manually if you need 'index' as the name

Example fix

// before
s.rename("index").plot.scatter()
// after
s.rename("x_val").plot.scatter()  # 'scatter' aliases to mark_point

if s.name == "index":
    s = s.rename("value")
getattr(s.plot, attr)()

try:
    chart = getattr(s.plot, attr)()
except ValueError:
    chart = getattr(s.rename("value").plot, attr)()

When it happens

Trigger: Calling any non-predefined plot attribute on a Series named 'index', e.g. s.rename("index").plot.scatter(), s.plot.area(), s.plot.bar().

Common situations: Same as plot.line: pandas-migrated frames with an 'index' column; hitting this via dynamic attribute access or when using mark aliases like 'scatter'.

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

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