matplotlib/matplotlib · error · ValueError

Unknown type of bbox

Error message

Unknown type of bbox

What it means

BboxImage accepts a bbox that is either a BboxBase instance or a callable taking a renderer and returning a Bbox. get_window_extent stores nothing else: any other type (tuple, list, ndarray, string, ...) is only detected when get_window_extent runs — during draw, contains, or pick — and then raises ValueError('Unknown type of bbox').

Source

Thrown at lib/matplotlib/image.py:1529

            colorizer=colorizer,
            interpolation=interpolation,
            origin=origin,
            filternorm=filternorm,
            filterrad=filterrad,
            resample=resample,
            **kwargs
        )
        self.bbox = bbox

    def get_window_extent(self, renderer=None):
        if isinstance(self.bbox, BboxBase):
            return self.bbox
        elif callable(self.bbox):
            if renderer is None:
                renderer = self.get_figure()._get_renderer()
            return self.bbox(renderer)
        else:
            raise ValueError("Unknown type of bbox")

    def contains(self, mouseevent):
        """Test whether the mouse event occurred within the image."""
        if self._different_canvas(mouseevent) or not self.get_visible():
            return False, {}
        x, y = mouseevent.x, mouseevent.y
        inside = self.get_window_extent().contains(x, y)
        return inside, {}

    def make_image(self, renderer, magnification=1.0, unsampled=False):
        # docstring inherited
        width, height = renderer.get_canvas_width_height()
        bbox_in = self.get_window_extent(renderer).frozen()
        bbox_in._points /= [width, height]
        bbox_out = self.get_window_extent(renderer)
        clip = Bbox([[0, 0], [width, height]])
        self._transform = BboxTransformTo(clip)
        return self._make_image(

View on GitHub (pinned to b379c1b69e)

Solutions

1. Wrap the coordinates: BboxImage(Bbox.from_bounds(x, y, w, h), ...) or Bbox([[x0, y0], [x1, y1]]).
2. For dynamic placement, pass a callable: BboxImage(lambda renderer: compute_bbox(renderer), ...).
3. Validate up front with isinstance(bbox, BboxBase) or callable(bbox).

Example fix

# before
im = BboxImage((0.1, 0.1, 0.9, 0.9), cmap='viridis')  # tuple -> ValueError at draw

# after
from matplotlib.transforms import Bbox
im = BboxImage(Bbox.from_bounds(0.1, 0.1, 0.8, 0.8), cmap='viridis')

from matplotlib.transforms import BboxBase

if not (isinstance(bbox, BboxBase) or callable(bbox)):
    bbox = Bbox.from_bounds(*bbox)  # accept 4-tuples defensively
im = BboxImage(bbox, ...)

from matplotlib.transforms import BboxBase

def is_valid_bbox_arg(b) -> bool:
    return isinstance(b, BboxBase) or callable(b)

When it happens

Trigger: BboxImage((0, 0, 1, 1), ...) — a plain 4-tuple or nested list passed instead of a Bbox; then fig.canvas.draw() or a mouseover contains() check triggers the error.

Common situations: Assuming matplotlib accepts extent-style tuples anywhere an extent is needed; wrapping BboxImage with dynamically computed rectangles but passing a tuple literal; copy-pasted examples using older/other APIs.

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

• Invalid bbox: {bbox}
• linestyles and positions are unequal sized sequences
• 'facecolor' or 'color' argument must be a valid color or seq
• fmt must be a str or callable
• autopct must be callable or a format string

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