matplotlib/matplotlib · error · TypeError

Invalid arguments to set_clip_path, of type {type(path).__na

Error message

Invalid arguments to set_clip_path, of type {type(path).__name__} and {type(transform).__name__}

What it means

set_clip_path accepts exactly four shapes: a Patch (optionally with a Transform), a Path plus a Transform, a TransformedPatchPath, or a TransformedPath. Anything else - list/tuple of vertices, ndarray, Bbox, string - leaves the success flag unset and raises TypeError 'Invalid arguments to set_clip_path, of type {path} and {transform}'.

Source

Thrown at lib/matplotlib/artist.py:881

                success = True
            elif isinstance(path, tuple):
                path, transform = path

        if path is None:
            self._clippath = None
            success = True
        elif isinstance(path, Path):
            self._clippath = TransformedPath(path, transform)
            success = True
        elif isinstance(path, TransformedPatchPath):
            self._clippath = path
            success = True
        elif isinstance(path, TransformedPath):
            self._clippath = path
            success = True

        if not success:
            raise TypeError(
                "Invalid arguments to set_clip_path, of type "
                f"{type(path).__name__} and {type(transform).__name__}")
        # This may result in the callbacks being hit twice, but guarantees they
        # will be hit at least once.
        self.pchanged()
        self.stale = True

    def get_alpha(self):
        """
        Return the alpha value used for blending - not supported on all
        backends.
        """
        return self._alpha

    def get_visible(self):
        """Return the visibility."""
        return self._visible

View on GitHub (pinned to b379c1b69e)

Solutions

1. Wrap vertices: from matplotlib.path import Path; artist.set_clip_path(Path(verts), transform=ax.transAxes) (or the relevant data transform)
2. For rectangle clips use set_clip_box(mpl.transforms.Bbox([[x0, y0], [x1, y1]]))
3. Pass a Patch (e.g. Circle, Polygon) directly - it carries its own transform: artist.set_clip_path(Circle((0, 0), 1, transform=ax.transData))
4. Reuse existing transformed paths (artist.get_clip_path()) when re-applying

Example fix

# before
verts = [(0, 0), (1, 0), (1, 1), (0, 0)]
im.set_clip_path(verts)  # TypeError: list is not a valid clip path

# after
from matplotlib.path import Path
im.set_clip_path(Path(verts), transform=ax.transAxes)

from matplotlib.path import Path
from matplotlib.patches import Patch
from matplotlib.transforms import Transform, TransformedPath

def is_valid_clip_args(path, transform=None):
    if isinstance(path, (Patch, TransformedPath)):
        return True
    return isinstance(path, Path) and isinstance(transform, Transform)

When it happens

Trigger: artist.set_clip_path([(0, 0), (1, 0), (1, 1)]) with raw vertices; passing a matplotlib.transforms.Bbox (that is set_clip_box's job); passing a Path but forgetting the second transform argument in code paths that require it; passing a clip rectangle created by another library.

Common situations: Clipping images/heatmaps to country or region outlines (vertices come from geo packages as arrays); porting code from other plotting libs where clip paths are plain point lists; quick rectangle clips where Bbox would be simpler.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Requested MovieWriter ({name}) not available
• cannot remove artist
• Can not reset the Axes. You are probably trying to reuse an
• Can not put single artist in more than one figure
• alpha must be numeric or None, not {type(alpha)}

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