matplotlib/matplotlib · error · RuntimeError

rgrids only defined for polar Axes

Error message

rgrids only defined for polar Axes

What it means

plt.rgrids() configures radial gridlines of a polar plot, but it operates on the CURRENT axes via gca() and checks the type: if the current axes is not a PolarAxes it raises RuntimeError('rgrids only defined for polar Axes'). After any cartesian plot (or at session start with a default Axes), the current axes is cartesian, so calling rgrids() blindly fails.

Source

Thrown at lib/matplotlib/pyplot.py:2553

    --------
    .pyplot.thetagrids
    .projections.polar.PolarAxes.set_rgrids
    .Axis.get_gridlines
    .Axis.get_ticklabels

    Examples
    --------
    ::

      # set the locations of the radial gridlines
      lines, labels = rgrids( (0.25, 0.5, 1.0) )

      # set the locations and labels of the radial gridlines
      lines, labels = rgrids( (0.25, 0.5, 1.0), ('Tom', 'Dick', 'Harry' ))
    """
    ax = gca()
    if not isinstance(ax, PolarAxes):
        raise RuntimeError('rgrids only defined for polar Axes')
    if all(p is None for p in [radii, labels, angle, fmt]) and not kwargs:
        lines_out: list[Line2D] = ax.yaxis.get_gridlines()
        labels_out: list[Text] = ax.yaxis.get_ticklabels()
    elif radii is None:
        raise TypeError("'radii' cannot be None when other parameters are passed")
    else:
        lines_out, labels_out = ax.set_rgrids(
            radii, labels=labels, angle=angle, fmt=fmt, **kwargs)
    return lines_out, labels_out


def thetagrids(
    angles: ArrayLike | None = None,
    labels: Sequence[str | Text] | None = None,
    fmt: str | None = None,
    **kwargs
) -> tuple[list[Line2D], list[Text]]:
    """

View on GitHub (pinned to b379c1b69e)

Solutions

1. Make the polar axes current first: plt.subplot(projection='polar') immediately before plt.rgrids(...)
2. Better, avoid current-axes coupling: ax = plt.subplot(projection='polar'); ax.set_rgrids((0.25, 0.5, 1.0), ...)
3. Check isinstance(plt.gca(), PolarAxes) before calling rgrids in shared code

Example fix

# before
plt.plot([1, 2], [3, 4])
plt.rgrids((0.25, 0.5, 1.0))  # RuntimeError: not polar

# after
ax = plt.subplot(projection='polar')
ax.set_rgrids((0.25, 0.5, 1.0))

import matplotlib.pyplot as plt
from matplotlib.projections.polar import PolarAxes

def rgrids_or_none(*args, **kwargs):
    if not isinstance(plt.gca(), PolarAxes):
        return None  # nothing to configure on cartesian axes
    return plt.rgrids(*args, **kwargs)

from matplotlib.projections.polar import PolarAxes
from matplotlib.axes import Axes

def is_polar(ax: Axes) -> bool:
    """True when ax supports rgrids/set_rgrids (radial gridlines)."""
    return isinstance(ax, PolarAxes)

When it happens

Trigger: plt.plot(x, y); plt.rgrids((0.25, 0.5, 1.0)); calling rgrids as the first pyplot command (gca() creates a default cartesian axes); plotting on a cartesian figure, then creating a polar axes that is not current, then calling rgrids.

Common situations: Copy-pasting a polar-grid snippet into a notebook whose current axes is cartesian; ordering bugs where rgrids runs before plt.subplot(projection='polar'); mixed figure layouts where the polar axes lost focus.

Related errors

• 'radii' cannot be None when other parameters are passed
• thetagrids only defined for polar Axes
• polar={polar}, yet projection={projection!r}. Only one of th
• Cannot set Axes adjustable to 'datalim' for Axes which overr
• Adjustable 'box' is not allowed in a twinned Axes; use 'data

AI-assisted analysis of matplotlib/matplotlib@b379c1b69e (2026-08-21). Data as JSON: /api/errors/26cba3cd53137c0d. Report an issue: GitHub.