roboflow/supervision · error · ValueError

Each RLE payload must contain 'size' and 'counts'.

Error message

Each RLE payload must contain 'size' and 'counts'.

What it means

Raised by CompactMask.from_coco_rle when an RLE mapping is missing the 'size' or 'counts' key. Both are mandatory: 'size' is validated against image_shape and 'counts' is decoded into the mask. The check is a friendly precondition that fails before a KeyError could escape.

Source

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

            )

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

        crop_rles: list[npt.NDArray[np.int32]] = []
        crop_shapes_list: list[tuple[int, int]] = []
        offsets_list: list[tuple[int, int]] = []

        for mask_idx, rle in enumerate(rles):
            if not isinstance(rle, Mapping):
                raise ValueError("Each RLE payload must be a mapping.")
            if "size" not in rle or "counts" not in rle:
                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(

View on GitHub (pinned to 7f254d9784)

Solutions

1. Rename your keys to exactly 'size' and 'counts' when building the payload.
2. If your source format is {'shape': ..., 'runs': ...}, translate: {'size': s['shape'], 'counts': s['runs']}.
3. Add an assertion loop over payloads checking both keys before calling from_coco_rle.

Example fix

# before
rles = [{"shape": [4, 4], "runs": [0, 2, 2, 2, 10]}]

# after
rles = [{"size": r["shape"], "counts": r["runs"]} for r in raw_rles]

missing = [i for i, r in enumerate(rles) if "size" not in r or "counts" not in r]
assert not missing, f"RLE payloads missing keys at indices {missing}"

def has_required_keys(rle) -> bool:
    return isinstance(rle, dict) and "size" in rle and "counts" in rle

When it happens

Trigger: Passing {'counts': [0,2,...]} without 'size', or {'size': [h, w]} without 'counts'; renamed keys from a custom format (e.g. 'shape'/'runs') not mapped to COCO names.

Common situations: Hand-rolled RLE dicts from internal pipelines using different key names; partial copies of COCO segmentation dicts that dropped a key; version drift in a producer service.

Related errors

• Each RLE payload must be a mapping.
• 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/18c39cfe20d7da2c. Report an issue: GitHub.