roboflow/supervision · error · ValueError

A LabelMe annotation file is missing the required 'imagePath

Error message

A LabelMe annotation file is missing the required 'imagePath' field or it is empty.

What it means

Raised while loading a LabelMe dataset when an annotation file's 'imagePath' field is missing, null, or an empty string. supervision needs imagePath to link the annotation to an image file in images_directory_path (it uses only the basename), so an absent value makes the pairing impossible and fails with this generic message.

Source

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

    classes = sorted(
        {
            shape.get("label")
            for entry in entries
            for shape in entry.get("shapes", [])
            if shape.get("shape_type") in SUPPORTED_SHAPE_TYPES
        }
        - {None}
    )
    class_to_index = {class_name: index for index, class_name in enumerate(classes)}

    image_paths: list[str] = []
    annotations: dict[str, Detections] = {}
    for entry in entries:
        shapes = entry.get("shapes", [])
        raw_image_path = entry.get("imagePath")
        if not raw_image_path:
            raise ValueError(
                "A LabelMe annotation file is missing the required "
                "'imagePath' field or it is empty."
            )
        # ponytail: basename-only, no symlink resolution — images_directory_path
        # 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."
            )

View on GitHub (pinned to 7f254d9784)

Solutions

Open the failing .json and add "imagePath": "<image file name>" matching a file in images_directory_path.
If your generator uses a different key, rename it to imagePath when writing.
If imagePath is a relative path with directories, that is fine — supervision takes the basename.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

def has_image_path(entry: dict) -> bool:
    """LabelMe entry must carry a non-empty imagePath string."""
    return bool(entry.get('imagePath'))

Try / catch

try:
    dataset = sv.DetectionDataset.from_labelme(images_dir, ann_dir)
except ValueError as e:
    if 'imagePath' in str(e):
        raise SystemExit(f'Add "imagePath" to the failing LabelMe JSON: {e}') from e
    raise

Prevention

Write imagePath whenever generating LabelMe JSON.
Keep the official LabelMe metadata block (imagePath/imageWidth/imageHeight) intact.
Automate checks: every .json's imagePath basename exists in the images dir.

When it happens

Trigger: DetectionDataset.from_labelme where a .json entry has no 'imagePath' key, imagePath: null, or imagePath: "" — typical of programmatically generated annotations that skip the field.

Common situations: Annotations created by export scripts that only write shapes; LabelMe files edited to remove metadata; schema drift from other tools that use a different key name (e.g. 'image_path').

Related errors

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