{"record":{"id":"15d8fd4ff67bcbd8","repo":"roboflow/supervision","slug":"labelme-annotation-for-image-name-requires-imag","errorCode":null,"errorMessage":"LabelMe annotation for {image_name} requires 'imageWidth' and 'imageHeight' to build masks, but they are missing or zero.","messagePattern":"LabelMe annotation for (.+?) requires 'imageWidth' and 'imageHeight' to build masks, but they are missing or zero\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/labelme.py","lineNumber":270,"sourceCode":"        # is trusted; annotation-driven traversal is neutralised by .name.\n        # See createml._resolve_image_path for the full .resolve()+parents pattern.\n        image_name = Path(raw_image_path).name\n        if not image_name or image_name in (\"..\", \".\"):\n            raise ValueError(\n                f\"LabelMe annotation has an invalid 'imagePath' {raw_image_path!r}.\"\n            )\n        image_path = str(Path(images_directory_path) / image_name)\n        if image_path in annotations:\n            raise ValueError(\n                f\"Duplicate image basename {image_name!r} resolved from multiple \"\n                \"annotation files. All annotation files must reference unique \"\n                \"image basenames.\"\n            )\n        with_masks = force_masks or any(\n            shape.get(\"shape_type\") == \"polygon\" for shape in shapes\n        )\n        if with_masks and not (entry.get(\"imageWidth\") and entry.get(\"imageHeight\")):\n            raise ValueError(\n                f\"LabelMe annotation for {image_name!r} requires \"\n                \"'imageWidth' and 'imageHeight' to build masks, but they are \"\n                \"missing or zero.\"\n            )\n        resolution_wh = (\n            int(entry.get(\"imageWidth\", 0)),\n            int(entry.get(\"imageHeight\", 0)),\n        )\n        annotations[image_path] = labelme_shapes_to_detections(\n            shapes=shapes,\n            class_to_index=class_to_index,\n            resolution_wh=resolution_wh,\n            with_masks=with_masks,\n        )\n        image_paths.append(image_path)\n\n    return classes, image_paths, annotations\n","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/labelme.py#L252-L288","documentation":"Raised when a LabelMe annotation needs raster masks (force_masks=True or any shape with shape_type 'polygon') but the JSON lacks usable 'imageWidth'/'imageHeight' metadata. Masks are allocated as a (H, W) boolean array per object, so the image dimensions must be present and nonzero; LabelMe normally writes them automatically, so their absence indicates an incomplete export.","triggerScenarios":"DetectionDataset.from_labelme(..., force_masks=True) on files without imageWidth/imageHeight, or from_labelme with default settings where any shape has shape_type \"polygon\" and the metadata fields are missing/zero.","commonSituations":"Annotations produced by scripts that write only shapes; JSON hand-minimized by stripping 'unneeded' metadata; files from tools other than the official LabelMe app.","solutions":["Add \"imageWidth\": <W>, \"imageHeight\": <H> to each failing .json (read the real size with cv2.imread(...).shape if unsure).","Fix the generator to always write both fields alongside imagePath.","If you do not need masks and no shapes are polygons, drop force_masks so the metadata is not required."],"exampleFix":"// before\n{\"shapes\": [...], \"imagePath\": \"img1.jpg\"}\n// after\n{\"shapes\": [...], \"imagePath\": \"img1.jpg\", \"imageWidth\": 640, \"imageHeight\": 480}","handlingStrategy":"validation","validationCode":"def mask_metadata_present(entry: dict, needs_masks: bool) -> bool:\n    \"\"\"Masks require nonzero imageWidth and imageHeight in the JSON.\"\"\"\n    if not needs_masks:\n        return True\n    return bool(entry.get('imageWidth')) and bool(entry.get('imageHeight'))","typeGuard":null,"tryCatchPattern":"try:\n    dataset = sv.DetectionDataset.from_labelme(images_dir, ann_dir, force_masks=True)\nexcept ValueError as e:\n    if 'imageWidth' in str(e):\n        raise SystemExit(f'Add imageWidth/imageHeight to the named JSON: {e}') from e\n    raise","preventionTips":["Always write imageWidth/imageHeight when generating LabelMe files.","Skip force_masks when you only need boxes and metadata is missing.","Backfill dimensions from the actual images with cv2 if needed."],"tags":["labelme","dataset","masks","json"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}