roboflow/supervision · error · ValueError

COCO RLE counts exceed int32 range.

Error message

COCO RLE counts exceed int32 range.

What it means

Raised while converting COCO RLE counts when any value, after casting to int64, falls outside the int32 range that the compact mask representation stores internally. Counts are deliberately narrowed to int32 for memory efficiency, and the code range-checks first so overflow is detected deterministically instead of wrapping silently.

Source

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

        ```
    """
    try:
        if isinstance(counts, bytes):
            counts = counts.decode("utf-8")
        if isinstance(counts, str):
            decoded_counts = _delta_decode(_base48_decode(counts))
            counts_arr = np.array(decoded_counts, dtype=np.int32)
        else:
            # Convert to int64 first, then range-check against int32 bounds before
            # narrowing. A direct int32 cast wraps silently on some numpy versions
            # and raises on others; this makes overflow detection deterministic.
            counts_arr64 = np.asarray(counts, dtype=np.int64)
            int32_info = np.iinfo(np.int32)
            if counts_arr64.size and (
                counts_arr64.max() > int32_info.max
                or counts_arr64.min() < int32_info.min
            ):
                raise ValueError("COCO RLE counts exceed int32 range.")
            counts_arr = counts_arr64.astype(np.int32)
    except (TypeError, ValueError, OverflowError) as exc:
        raise ValueError("Invalid COCO RLE counts.") from exc

    if counts_arr.ndim != 1:
        raise ValueError("COCO RLE counts must be one-dimensional.")
    if counts_arr.size == 0:
        raise ValueError("COCO RLE counts cannot be empty.")
    if np.any(counts_arr < 0):
        raise ValueError("COCO RLE counts must be non-negative.")
    return counts_arr


def _rle_resize(
    rle: npt.NDArray[np.int32],
    crop_h: int,
    crop_w: int,
    new_crop_h: int,

View on GitHub (pinned to 7f254d9784)

Solutions

1. Verify the image dimensions used to encode the RLE — a legit run cannot exceed h*w; huge counts usually mean the encoder saw wrong (huge) dimensions.
2. Regenerate counts with pycocotools.mask.encode from the true-sized boolean mask.
3. Print the offending counts array (values > 2**31-1) and trace where they were produced.

Example fix

# before — encoder used wrong dims, produced run of 10**10
counts = [0, 10_000_000_000, 16]

# after — regenerate at true size
from pycocotools import mask as mask_utils
rle = mask_utils.encode(np.asfortranarray(mask.astype(np.uint8)))
cm = CompactMask.from_coco_rle([{"size": [h, w], "counts": rle["counts"]}], xyxy, image_shape=(h, w))

import numpy as np
INT32_MAX = np.iinfo(np.int32).max
arr = np.asarray(rle["counts"], dtype=np.int64)
assert arr.size == 0 or (arr.max() <= INT32_MAX and arr.min() >= -INT32_MAX - 1)

try:
    cm = sv.CompactMask.from_coco_rle(rles, xyxy, image_shape=shape)
except ValueError as e:
    if "int32 range" in str(e):
        raise ValueError("RLE encoded against wrong image dims — regenerate") from e
    raise

When it happens

Trigger: Passing a counts element greater than 2147483647 or less than -2147483648 to CompactMask.from_coco_rle — typically a wrong payload (e.g. raw bytes values, an id, or a decoding bug) rather than a legitimate run length.

Common situations: A single gigantic run covering an absurdly large image (dimension bug upstream); passing compressed-ASCII counts decoded as huge integers; custom encoders emitting pixel indices instead of run lengths.

Related errors

• COCO RLE counts must be one-dimensional.
• COCO RLE counts cannot be empty.
• COCO RLE counts must be non-negative.
• Invalid COCO RLE counts.
• image_shape must contain positive height and width.

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