{"record":{"id":"115dc938f3208fc2","repo":"roboflow/supervision","slug":"image-shape-must-contain-positive-height-and-width","errorCode":null,"errorMessage":"image_shape must contain positive height and width.","messagePattern":"image_shape must contain positive height and width\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/compact_mask.py","lineNumber":784,"sourceCode":"            ```pycon\n            >>> import numpy as np\n            >>> from supervision.detection.compact_mask import CompactMask\n            >>> # 4x4 image with a 2x2 True block at the top-left corner.\n            >>> # Uncompressed F-order COCO counts: F=0, T=2, F=2, T=2, F=10\n            >>> # (column-major: col0=[T,T,F,F], col1=[T,T,F,F], cols2-3 all F).\n            >>> rles = [{\"size\": [4, 4], \"counts\": [0, 2, 2, 2, 10]}]\n            >>> xyxy = np.array([[0, 0, 3, 3]], dtype=np.float32)\n            >>> cm = CompactMask.from_coco_rle(rles, xyxy, image_shape=(4, 4))\n            >>> 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),","sourceCodeStart":766,"sourceCodeEnd":802,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/compact_mask.py#L766-L802","documentation":"Raised by CompactMask.from_coco_rle when image_shape[0] (height) or image_shape[1] (width) is zero or negative. The image shape defines the canvas the RLE must cover and is validated before any mask parsing, since a non-positive canvas makes area checks and cropping meaningless.","triggerScenarios":"Calling CompactMask.from_coco_rle(rles, xyxy, image_shape=(0, 480)) or with negative dims; deriving image_shape from image metadata that failed to load (e.g. None coerced to 0) or from a mismatched variable.","commonSituations":"Passing width-first (w, h) tuples where a field happened to be 0; computing shape from cv2.imread that returned None on a missing file and then indexing .shape of the wrong object; default-initialized placeholders never replaced.","solutions":["Verify the source of image_shape — read the actual image with cv2.imread and use img.shape[:2] (h, w order).","Check for failed image loads before computing the shape (if img is None: handle missing file).","Confirm you pass (height, width), not (width, height) with a stray zero."],"exampleFix":"# before\nimage_shape = (img_w, img_h) if img is not None else (0, 0)\n\n# after\nimg = cv2.imread(path)\nif img is None:\n    raise FileNotFoundError(path)\nimage_shape = img.shape[:2]  # (h, w)","handlingStrategy":"validation","validationCode":"h, w = image_shape\nassert h > 0 and w > 0, f\"image_shape must be positive, got {(h, w)}\"","typeGuard":"def is_valid_image_shape(shape) -> bool:\n    return (\n        isinstance(shape, (tuple, list))\n        and len(shape) == 2\n        and all(isinstance(v, (int, np.integer)) and v > 0 for v in shape)\n    )","tryCatchPattern":"try:\n    cm = sv.CompactMask.from_coco_rle(rles, xyxy, image_shape=shape)\nexcept ValueError as e:\n    if \"positive height and width\" in str(e):\n        shape = cv2.imread(path).shape[:2]\n    else:\n        raise","preventionTips":["Derive image_shape from the loaded image (img.shape[:2]), never from defaults or unrelated variables.","Check cv2.imread for None before touching .shape.","Remember order is (height, width) everywhere in this API."],"tags":["compact-mask","coco","rle","image-shape","validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}