{"record":{"id":"15d417d488082ef5","repo":"roboflow/supervision","slug":"xyxy-must-have-shape-n-4-where-n-matches-the-n","errorCode":null,"errorMessage":"xyxy must have shape (N, 4), where N matches the number of RLEs.","messagePattern":"xyxy must have shape \\(N, 4\\), where N matches the number of RLEs\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/compact_mask.py","lineNumber":793,"sourceCode":"            >>> cm.shape\n            (1, 4, 4)\n            >>> cm.area.tolist()\n            [4]\n\n            ```\n        \"\"\"\n        img_h, img_w = (int(image_shape[0]), int(image_shape[1]))\n        if img_h <= 0 or img_w <= 0:\n            raise ValueError(\"image_shape must contain positive height and width.\")\n        if img_h > _MAX_IMAGE_DIMENSION or img_w > _MAX_IMAGE_DIMENSION:\n            raise ValueError(\n                f\"image_shape {(img_h, img_w)} exceeds the maximum allowed dimension \"\n                f\"of {_MAX_IMAGE_DIMENSION} pixels per side.\"\n            )\n\n        xyxy_arr = np.asarray(xyxy)\n        if xyxy_arr.shape != (len(rles), 4):\n            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.\")","sourceCodeStart":775,"sourceCodeEnd":811,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/compact_mask.py#L775-L811","documentation":"Raised by CompactMask.from_coco_rle when the xyxy bounding-box array's shape is not exactly (N, 4) where N equals len(rles). Each RLE must be paired with one bounding box that defines its crop region; a mismatched or wrongly shaped xyxy makes the pairing impossible.","triggerScenarios":"Passing 3 boxes with 5 RLEs; passing xyxy of shape (N, 5) (e.g. xywh instead of xyxy); passing a flat array of shape (4,) for a single mask instead of (1, 4).","commonSituations":"COCO annotations store [x, y, width, height] — passing bbox unconverted produces (N, 4) but semantically wrong, while filtering rles without filtering xyxy (or vice versa) produces the N mismatch; forgetting xyxy=np.array([[...]]) nesting for one mask.","solutions":["Ensure one box per RLE: len(xyxy) == len(rles), and each row is [x1, y1, x2, y2].","Convert COCO bbox xywh -> xyxy before the call: xyxy = xywh.copy(); xyxy[:, 2:] += xyxy[:, :2].","For a single mask use np.array([[x1, y1, x2, y2]]) (leading bracket keeps shape (1, 4))."],"exampleFix":"# before\nxyxy = np.array(anns[\"bbox\"])  # xywh, and count mismatch\n\n# after\nxywh = np.array([a[\"bbox\"]] * 0 + [a[\"bbox\"] for a in anns])\nxyxy = np.array([a[\"bbox\"] for a in anns], dtype=np.float32)\nxyxy[:, 2:] += xyxy[:, :2]","handlingStrategy":"validation","validationCode":"import numpy as np\nxyxy = np.asarray(xyxy, dtype=np.float32)\nassert xyxy.shape == (len(rles), 4), f\"need ({len(rles)}, 4), got {xyxy.shape}\"","typeGuard":"def is_valid_xyxy_for(xyxy, rles) -> bool:\n    xyxy = np.asarray(xyxy)\n    return xyxy.ndim == 2 and xyxy.shape == (len(rles), 4)","tryCatchPattern":null,"preventionTips":["Filter rles and xyxy together (same mask/filter condition) so they stay paired.","Convert COCO bbox xywh to xyxy (x2=x1+w; y2=y1+h) before the call.","Use np.array([[x1, y1, x2, y2]]) — double brackets — for a single mask."],"tags":["compact-mask","coco","rle","bounding-box","shape-mismatch"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}