roboflow/supervision · error · ValueError

LabelMe annotation for {image_name} requires 'imageWidth' an

Error message

LabelMe annotation for {image_name} requires 'imageWidth' and 'imageHeight' to build masks, but they are missing or zero.

What it means

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.

Source

Thrown at src/supervision/dataset/formats/labelme.py:270

        # is trusted; annotation-driven traversal is neutralised by .name.
        # See createml._resolve_image_path for the full .resolve()+parents pattern.
        image_name = Path(raw_image_path).name
        if not image_name or image_name in ("..", "."):
            raise ValueError(
                f"LabelMe annotation has an invalid 'imagePath' {raw_image_path!r}."
            )
        image_path = str(Path(images_directory_path) / image_name)
        if image_path in annotations:
            raise ValueError(
                f"Duplicate image basename {image_name!r} resolved from multiple "
                "annotation files. All annotation files must reference unique "
                "image basenames."
            )
        with_masks = force_masks or any(
            shape.get("shape_type") == "polygon" for shape in shapes
        )
        if with_masks and not (entry.get("imageWidth") and entry.get("imageHeight")):
            raise ValueError(
                f"LabelMe annotation for {image_name!r} requires "
                "'imageWidth' and 'imageHeight' to build masks, but they are "
                "missing or zero."
            )
        resolution_wh = (
            int(entry.get("imageWidth", 0)),
            int(entry.get("imageHeight", 0)),
        )
        annotations[image_path] = labelme_shapes_to_detections(
            shapes=shapes,
            class_to_index=class_to_index,
            resolution_wh=resolution_wh,
            with_masks=with_masks,
        )
        image_paths.append(image_path)

    return classes, image_paths, annotations

View on GitHub (pinned to 7f254d9784)

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.

Example fix

// before
{"shapes": [...], "imagePath": "img1.jpg"}
// after
{"shapes": [...], "imagePath": "img1.jpg", "imageWidth": 640, "imageHeight": 480}

Defensive patterns

Strategy: validation

Validate before calling

def mask_metadata_present(entry: dict, needs_masks: bool) -> bool:
    """Masks require nonzero imageWidth and imageHeight in the JSON."""
    if not needs_masks:
        return True
    return bool(entry.get('imageWidth')) and bool(entry.get('imageHeight'))

Try / catch

try:
    dataset = sv.DetectionDataset.from_labelme(images_dir, ann_dir, force_masks=True)
except ValueError as e:
    if 'imageWidth' in str(e):
        raise SystemExit(f'Add imageWidth/imageHeight to the named JSON: {e}') from e
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: Annotations produced by scripts that write only shapes; JSON hand-minimized by stripping 'unneeded' metadata; files from tools other than the official LabelMe app.

Related errors

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/15d8fd4ff67bcbd8. Report an issue: GitHub.