roboflow/supervision · error · ValueError

The sum of COCO RLE counts must match the image area.

Error message

The sum of COCO RLE counts must match the image area.

What it means

Raised by CompactMask.from_coco_rle when the sum of the RLE counts does not equal height*width of image_shape. In COCO's uncompressed column-major RLE, the alternating run lengths must exactly cover the whole canvas; a sum mismatch means the counts were truncated, corrupted, or encoded for a different resolution.

Source

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

                raise ValueError("Each RLE payload must contain 'size' and 'counts'.")

            try:
                # COCO standard: size=[height, width] (h,w order per pycocotools spec)
                rle_h, rle_w = rle["size"]
                rle_h = int(rle_h)
                rle_w = int(rle_w)
            except (TypeError, ValueError) as exc:
                raise ValueError("RLE size must be [height, width].") from exc

            if (rle_h, rle_w) != (img_h, img_w):
                raise ValueError(
                    f"RLE size {(rle_h, rle_w)} must match image_shape "
                    f"{(img_h, img_w)}."
                )

            counts = _coco_rle_counts_to_array(rle["counts"])
            if int(np.sum(counts, dtype=np.int64)) != img_h * img_w:
                raise ValueError(
                    "The sum of COCO RLE counts must match the image area."
                )

            x1, y1, x2, y2 = xyxy_arr[mask_idx]
            x1i, y1i, x2i, y2i = int(x1), int(y1), int(x2), int(y2)
            x1c = max(0, min(x1i, img_w - 1))
            y1c = max(0, min(y1i, img_h - 1))

            if (
                x2i < x1i
                or y2i < y1i
                or x2i < 0
                or y2i < 0
                or x1i >= img_w
                or y1i >= img_h
            ):
                crop_rles.append(np.array([1], dtype=np.int32))
                crop_shapes_list.append((1, 1))

View on GitHub (pinned to 7f254d9784)

Solutions

1. Regenerate counts from the full-image boolean mask with pycocotools.mask.encode — the output always sums to h*w.
2. If hand-building runs, append the final background run so the total equals h*w.
3. Check the annotation pipeline's resize step so encode size == image_shape.

Example fix

# before — missing trailing run (sum 4 for 4x4=16)
counts = [0, 2, 2]

# after
counts = [0, 2, 2, 12]  # runs sum to 16 == 4*4

import numpy as np
h, w = image_shape
for r in rles:
    total = int(np.sum(np.asarray(r["counts"], dtype=np.int64)))
    assert total == h * w, f"counts sum {total} != area {h * w}"

When it happens

Trigger: Passing counts=[0, 2, 2] for a 4x4 image (sum 4 != 16); dropping trailing runs; encoding on a differently sized canvas than image_shape claims; manually editing counts.

Common situations: Truncated JSON; custom encoders that stop at the last foreground run and omit the trailing background run; mixing annotations from a resized copy of the dataset.

Related errors

• COCO RLE counts must be non-negative.
• COCO RLE counts must be one-dimensional.
• COCO RLE counts cannot be empty.
• 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/67cea9d34eb50037. Report an issue: GitHub.