{"record":{"id":"f86fd29a8f2fa37e","repo":"roboflow/supervision","slug":"each-rle-payload-must-be-a-mapping","errorCode":null,"errorMessage":"Each RLE payload must be a mapping.","messagePattern":"Each RLE payload must be a mapping\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/compact_mask.py","lineNumber":811,"sourceCode":"            raise ValueError(\n                \"xyxy must have shape (N, 4), where N matches the number of RLEs.\"\n            )\n\n        if len(rles) == 0:\n            return cls(\n                [],\n                np.empty((0, 2), dtype=np.int32),\n                np.empty((0, 2), dtype=np.int32),\n                (img_h, img_w),\n            )\n\n        crop_rles: list[npt.NDArray[np.int32]] = []\n        crop_shapes_list: list[tuple[int, int]] = []\n        offsets_list: list[tuple[int, int]] = []\n\n        for mask_idx, rle in enumerate(rles):\n            if not isinstance(rle, Mapping):\n                raise ValueError(\"Each RLE payload must be a mapping.\")\n            if \"size\" not in rle or \"counts\" not in rle:\n                raise ValueError(\"Each RLE payload must contain 'size' and 'counts'.\")\n\n            try:\n                # COCO standard: size=[height, width] (h,w order per pycocotools spec)\n                rle_h, rle_w = rle[\"size\"]\n                rle_h = int(rle_h)\n                rle_w = int(rle_w)\n            except (TypeError, ValueError) as exc:\n                raise ValueError(\"RLE size must be [height, width].\") from exc\n\n            if (rle_h, rle_w) != (img_h, img_w):\n                raise ValueError(\n                    f\"RLE size {(rle_h, rle_w)} must match image_shape \"\n                    f\"{(img_h, img_w)}.\"\n                )\n\n            counts = _coco_rle_counts_to_array(rle[\"counts\"])","sourceCodeStart":793,"sourceCodeEnd":829,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/compact_mask.py#L793-L829","documentation":"Raised by CompactMask.from_coco_rle when an element of the rles sequence is not a Mapping (dict-like). Each RLE payload must expose 'size' and 'counts' keys, which requires mapping access; lists, tuples, strings, or None are rejected with this error before any key lookup.","triggerScenarios":"Passing rles = [[4, 4], ...] (positional lists), rles = [None], rles = ['01b...'] (bare compressed strings), or a numpy structured array instead of [{'size': ..., 'counts': ...}, ...].","commonSituations":"Grabbing ann['segmentation']['counts'] strings from COCO JSON and zipping them into lists instead of rebuilding dicts; passing pycocotools RLE objects (which are dicts and fine) mixed with raw strings; None placeholders for missing masks.","solutions":["Normalize each payload to a dict with the two keys: {'size': [h, w], 'counts': counts}.","Filter out None/empty segmentation entries before building the list.","If you have parallel arrays of sizes and counts, zip them into dicts before the call."],"exampleFix":"# before\nrles = [ann[\"segmentation\"][\"counts\"] for ann in anns]\n\n# after\nrles = [{\"size\": ann[\"segmentation\"][\"size\"],\n         \"counts\": ann[\"segmentation\"][\"counts\"]} for ann in anns]","handlingStrategy":"type-guard","validationCode":"from collections.abc import Mapping\nassert all(isinstance(r, Mapping) and {\"size\", \"counts\"} <= r.keys() for r in rles), \"bad RLE payload\"","typeGuard":"from collections.abc import Mapping\n\ndef is_coco_rle_payload(obj) -> bool:\n    return isinstance(obj, Mapping) and \"size\" in obj and \"counts\" in obj","tryCatchPattern":"try:\n    cm = sv.CompactMask.from_coco_rle(rles, xyxy, image_shape=shape)\nexcept ValueError as e:\n    if \"must be a mapping\" in str(e):\n        rles = [r if isinstance(r, dict) else {\"size\": s, \"counts\": r} for r, s in zip(rles, sizes)]\n    else:\n        raise","preventionTips":["Always materialize payloads as dicts with exactly 'size' and 'counts'.","Filter None segmentation entries when walking COCO annotations.","Zip parallel size/counts arrays into dicts at the boundary of your code."],"tags":["coco","rle","compact-mask","type-error","api-contract"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}