roboflow/supervision · error · ValueError

image_shape {(img_h, img_w)} exceeds the maximum allowed dim

Error message

image_shape {(img_h, img_w)} exceeds the maximum allowed dimension of {_MAX_IMAGE_DIMENSION} pixels per side.

What it means

Raised by CompactMask.from_coco_rle when either image dimension exceeds the module-level constant _MAX_IMAGE_DIMENSION. The cap bounds memory/CPU cost of decoding and storing per-mask RLE crops, so absurdly large shapes (typically from corrupt metadata) are rejected early with the allowed maximum stated in the message.

Source

Thrown at src/supervision/detection/compact_mask.py:786

            >>> from supervision.detection.compact_mask import CompactMask
            >>> # 4x4 image with a 2x2 True block at the top-left corner.
            >>> # Uncompressed F-order COCO counts: F=0, T=2, F=2, T=2, F=10
            >>> # (column-major: col0=[T,T,F,F], col1=[T,T,F,F], cols2-3 all F).
            >>> rles = [{"size": [4, 4], "counts": [0, 2, 2, 2, 10]}]
            >>> xyxy = np.array([[0, 0, 3, 3]], dtype=np.float32)
            >>> cm = CompactMask.from_coco_rle(rles, xyxy, image_shape=(4, 4))
            >>> cm.shape
            (1, 4, 4)
            >>> cm.area.tolist()
            [4]

            ```
        """
        img_h, img_w = (int(image_shape[0]), int(image_shape[1]))
        if img_h <= 0 or img_w <= 0:
            raise ValueError("image_shape must contain positive height and width.")
        if img_h > _MAX_IMAGE_DIMENSION or img_w > _MAX_IMAGE_DIMENSION:
            raise ValueError(
                f"image_shape {(img_h, img_w)} exceeds the maximum allowed dimension "
                f"of {_MAX_IMAGE_DIMENSION} pixels per side."
            )

        xyxy_arr = np.asarray(xyxy)
        if xyxy_arr.shape != (len(rles), 4):
            raise ValueError(
                "xyxy must have shape (N, 4), where N matches the number of RLEs."
            )

        if len(rles) == 0:
            return cls(
                [],
                np.empty((0, 2), dtype=np.int32),
                np.empty((0, 2), dtype=np.int32),
                (img_h, img_w),
            )

View on GitHub (pinned to 7f254d9784)

Solutions

1. Print the actual image_shape you pass and compare against the real image dimensions from cv2.imread(...).shape.
2. If you genuinely have a very large image, slice/tile it (e.g. InferenceSlicer) and build CompactMask per tile with tile-sized image_shape.
3. Fix the metadata source if headers are corrupt.

Example fix

# before
cm = CompactMask.from_coco_rle(rles, xyxy, image_shape=(h * 1000, w * 1000))

# after
cm = CompactMask.from_coco_rle(rles, xyxy, image_shape=(h, w))

MAX_DIM = 65535  # keep in sync with installed supervision's _MAX_IMAGE_DIMENSION
h, w = image_shape
assert 0 < h <= MAX_DIM and 0 < w <= MAX_DIM, f"image too large: {(h, w)}"

try:
    cm = sv.CompactMask.from_coco_rle(rles, xyxy, image_shape=shape)
except ValueError as e:
    if "maximum allowed dimension" in str(e):
        raise ValueError("tile the image before building CompactMask") from e
    raise

When it happens

Trigger: Passing image_shape=(100000, 100000) or similar oversized dims; unit confusion such as passing bytes-per-row instead of pixels; shapes sourced from a malformed image header or a typo with extra zeros.

Common situations: Corrupt image metadata (EXIF/header) reporting huge dimensions; passing shape multiplied twice; loading a huge tiled scan/WSI image without slicing first.

Related errors

• image_shape must contain positive height and width.
• RLE size {(rle_h, rle_w)} must match image_shape {(img_h, im
• COCO RLE counts must be one-dimensional.
• COCO RLE counts cannot be empty.
• COCO RLE counts must be non-negative.

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/31a2381c022a60da. Report an issue: GitHub.