roboflow/supervision · error · ValueError

Duplicate image basename {image_name} resolved from multiple

Error message

Duplicate image basename {image_name} resolved from multiple annotation files. All annotation files must reference unique image basenames.

What it means

Raised when two different LabelMe annotation files reference imagePath values whose basenames collapse to the same image path. Detections are stored in a dict keyed by resolved image path, so a duplicate would silently overwrite one file's annotations; supervision instead fails and asks that all annotation files reference unique image basenames.

Source

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

    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."
            )
        resolution_wh = (
            int(entry.get("imageWidth", 0)),
            int(entry.get("imageHeight", 0)),
        )
        annotations[image_path] = labelme_shapes_to_detections(

View on GitHub (pinned to 7f254d9784)

Solutions

Search the annotations directory for JSONs referencing the duplicate basename named in the error: grep -l '"img1.jpg"' -r annotations_dir.
Delete or move the stale duplicate annotation (usually from an old copy or another annotator).
If two legitimate annotation sets exist for the same images, keep them in separate dataset directories and load separately.
Ensure your export pipeline never writes two annotation files whose imagePath basenames collide.

Example fix

# before
annotations/a.json -> "imagePath": "img1.jpg"
annotations/b.json -> "imagePath": "img1.jpg"  # duplicate
# after
annotations/a.json -> "imagePath": "img1.jpg"
annotations/old/b.json removed

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
from collections import Counter

def unique_image_basenames(json_entries: list[dict]) -> bool:
    """All LabelMe imagePath basenames must be unique across entries."""
    names = [Path(e['imagePath']).name for e in json_entries if e.get('imagePath')]
    return max(Counter(names).values(), default=1) == 1

Try / catch

try:
    dataset = sv.DetectionDataset.from_labelme(images_dir, ann_dir)
except ValueError as e:
    if 'Duplicate image basename' in str(e):
        raise SystemExit(f'Remove the stale duplicate annotation: {e}') from e
    raise

Prevention

One annotations directory per annotation pass; do not merge annotator folders blindly.
Clean old copies of JSON when copying/renaming dataset folders.
Remember only the imagePath basename matters — directory parts are stripped.

When it happens

Trigger: DetectionDataset.from_labelme where e.g. a/ann1.json has imagePath "img1.jpg" and b/ann2.json has imagePath "../img1.jpg" — both basename to img1.jpg and resolve to the same path under images_directory_path.

Common situations: Merging annotation folders from multiple annotators of the same images; copying a project and keeping both copies of JSON in the annotations dir; annotating the same image in two subfolders; imagePath values differing only in directory components (basename is what counts).

Related errors

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