{"record":{"id":"d8857da6e73954bc","repo":"roboflow/supervision","slug":"coco-rle-counts-exceed-int32-range","errorCode":null,"errorMessage":"COCO RLE counts exceed int32 range.","messagePattern":"COCO RLE counts exceed int32 range\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/compact_mask.py","lineNumber":403,"sourceCode":"        ```\n    \"\"\"\n    try:\n        if isinstance(counts, bytes):\n            counts = counts.decode(\"utf-8\")\n        if isinstance(counts, str):\n            decoded_counts = _delta_decode(_base48_decode(counts))\n            counts_arr = np.array(decoded_counts, dtype=np.int32)\n        else:\n            # Convert to int64 first, then range-check against int32 bounds before\n            # narrowing. A direct int32 cast wraps silently on some numpy versions\n            # and raises on others; this makes overflow detection deterministic.\n            counts_arr64 = np.asarray(counts, dtype=np.int64)\n            int32_info = np.iinfo(np.int32)\n            if counts_arr64.size and (\n                counts_arr64.max() > int32_info.max\n                or counts_arr64.min() < int32_info.min\n            ):\n                raise ValueError(\"COCO RLE counts exceed int32 range.\")\n            counts_arr = counts_arr64.astype(np.int32)\n    except (TypeError, ValueError, OverflowError) as exc:\n        raise ValueError(\"Invalid COCO RLE counts.\") from exc\n\n    if counts_arr.ndim != 1:\n        raise ValueError(\"COCO RLE counts must be one-dimensional.\")\n    if counts_arr.size == 0:\n        raise ValueError(\"COCO RLE counts cannot be empty.\")\n    if np.any(counts_arr < 0):\n        raise ValueError(\"COCO RLE counts must be non-negative.\")\n    return counts_arr\n\n\ndef _rle_resize(\n    rle: npt.NDArray[np.int32],\n    crop_h: int,\n    crop_w: int,\n    new_crop_h: int,","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/compact_mask.py#L385-L421","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Regenerate counts with pycocotools.mask.encode from the true-sized boolean mask.","Print the offending counts array (values > 2**31-1) and trace where they were produced."],"exampleFix":"# before — encoder used wrong dims, produced run of 10**10\ncounts = [0, 10_000_000_000, 16]\n\n# after — regenerate at true size\nfrom pycocotools import mask as mask_utils\nrle = mask_utils.encode(np.asfortranarray(mask.astype(np.uint8)))\ncm = CompactMask.from_coco_rle([{\"size\": [h, w], \"counts\": rle[\"counts\"]}], xyxy, image_shape=(h, w))","handlingStrategy":"validation","validationCode":"import numpy as np\nINT32_MAX = np.iinfo(np.int32).max\narr = np.asarray(rle[\"counts\"], dtype=np.int64)\nassert arr.size == 0 or (arr.max() <= INT32_MAX and arr.min() >= -INT32_MAX - 1)","typeGuard":null,"tryCatchPattern":"try:\n    cm = sv.CompactMask.from_coco_rle(rles, xyxy, image_shape=shape)\nexcept ValueError as e:\n    if \"int32 range\" in str(e):\n        raise ValueError(\"RLE encoded against wrong image dims — regenerate\") from e\n    raise","preventionTips":["A run length can never exceed h*w — huge counts always indicate an encoder bug upstream.","Regenerate counts with pycocotools.mask.encode at the true image size.","Never feed decoded compressed-ASCII values or pixel indices as counts."],"tags":["coco","rle","compact-mask","overflow","int32"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}