roboflow/supervision · error · ValueError

LabelMe annotation has an invalid 'imagePath' {raw_image_pat

Error message

LabelMe annotation has an invalid 'imagePath' {raw_image_path}.

What it means

Raised when a LabelMe annotation's imagePath resolves to an invalid basename: Path(imagePath).name is empty or the special entries '..' or '.'. This is a hardening check — annotation-controlled path traversal is neutralized by taking the basename only, and degenerate values that would map outside/nowhere are rejected instead of silently producing a broken image path.

Source

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

    )
    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."
            )
        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."
            )

View on GitHub (pinned to 7f254d9784)

Solutions

Set imagePath in the failing JSON to a real image filename, e.g. "img_042.png".
If generated programmatically, validate/normalize the value before writing (must have a non-trivial basename).
Regenerate annotations whose imagePath came from empty template variables.

Example fix

// before
"imagePath": "."
// after
"imagePath": "img_042.png"

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def image_path_safe(raw: object) -> bool:
    """imagePath must yield a real, non-special basename."""
    if not isinstance(raw, str) or not raw:
        return False
    name = Path(raw).name
    return bool(name) and name not in ('..', '.')

Try / catch

try:
    dataset = sv.DetectionDataset.from_labelme(images_dir, ann_dir)
except ValueError as e:
    if "invalid 'imagePath'" in str(e):
        raise SystemExit(f'Replace the degenerate imagePath value: {e}') from e
    raise

Prevention

Never write template-derived imagePath values without validation.
Sanitize untrusted annotation JSON before ingestion pipelines.
Prefer basename-only imagePath values in generated files.

When it happens

Trigger: DetectionDataset.from_labelme where imagePath is "/" (basename empty), "..", ".", or a path ending in a separator such that Path(...).name degenerates.

Common situations: Malformed or adversarial JSON values; scripts writing imagePath from an unset variable producing '.'/''; manual edits that leave placeholder paths.

Related errors

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