roboflow/supervision · error · ValueError

the sum of the number of pixels in the RLE must be the same

Error message

the sum of the number of pixels in the RLE must be the same as the number of pixels in the expected mask

What it means

When decoding a COCO-style run-length encoding back into a mask, the sum of the RLE run counts must equal width*height of the supplied resolution — every pixel is accounted for by alternating runs. A mismatch means the RLE and resolution_wh disagree (wrong resolution, truncated counts, or an RLE produced under column-major vs row-major differences), so reconstruction would be ill-defined.

Source

Thrown at src/supervision/detection/utils/converters.py:717

               [False, False, False, False]])

        ```
    """
    if isinstance(rle, bytes):
        rle = rle.decode("utf-8")
    if isinstance(rle, str):
        counts: npt.NDArray[np.int32] = np.array(
            _delta_decode(_base48_decode(rle)), dtype=np.int32
        )
    elif isinstance(rle, list):
        counts = np.array(rle, dtype=np.int32)
    else:
        counts = np.asarray(rle, dtype=np.int32)

    width, height = resolution_wh

    if width * height != np.sum(counts):
        raise ValueError(
            "the sum of the number of pixels in the RLE must be the same "
            "as the number of pixels in the expected mask"
        )

    return _rle_counts_to_mask(counts, height, width)


def mask_to_rle(
    mask: npt.NDArray[np.bool_], compressed: bool = False
) -> list[int] | str:
    """
    Converts a binary mask into a COCO run-length encoding (RLE).

    Produces RLE in the COCO format used by ``pycocotools``: pixels are counted
    in **column-major (Fortran) order** — top-to-bottom within each column,
    left-to-right across columns. The output is directly compatible with
    ``pycocotools.mask.decode`` and COCO annotation JSON files.

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass the exact resolution used at encode time — store it alongside the RLE.
2. Double-check tuple order: supervision expects resolution as (width, height).
3. If the RLE came from pycocotools, convert counts orientation before decoding with this API.
4. Sanity check: assert sum(counts) == w * h in your data loader before decoding.

Example fix

# before
 mask = sv.rle_to_mask(rle=stored_rle, resolution_wh=(1920, 1080))  # encoded at 640x480

# after
 mask = sv.rle_to_mask(rle=stored_rle, resolution_wh=stored_resolution_wh)

w, h = resolution_wh
if int(np.sum(counts)) != w * h:
    raise ValueError(f"RLE sum {np.sum(counts)} != {w}x{h}={w * h}; wrong resolution?")

try:
    mask = sv.rle_to_mask(rle=rle, resolution_wh=wh)
except ValueError as e:
    logger.error("RLE/resolution mismatch for record %s: %s", record_id, e)
    raise

When it happens

Trigger: Calling rle_to_mask(rle, resolution_wh) with a resolution different from the one used to encode (e.g. encoding at 640x480, decoding at 1920x1080); passing a compressed string decoded with the wrong scheme; hand-modified or truncated count lists.

Common situations: Resizing images after storing RLEs without updating resolution metadata; mixing COCO API RLEs (column-major) with supervision's encoder; storing resolution as (height, width) and swapping the tuple.

Related errors

• 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.
• Invalid COCO RLE counts.

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