roboflow/supervision · error · ValueError

COCO annotation refers to image {image_name}, which resolves

Error message

COCO annotation refers to image {image_name}, which resolves to directory {resolved_image_path}. Expected a path to an image file.

What it means

Raised by load_coco_annotations when the resolved path for a COCO image entry is an existing directory rather than a file. The loader accepts subdirectories in file_name, but the final component must name an image file; resolving to a directory means the annotation is unusable.

Source

Thrown at src/supervision/dataset/formats/coco.py:547

            raise ValueError(
                f"COCO annotation refers to image {image_name!r}, which "
                f"produces an invalid path: {exc}"
            ) from exc
        if resolved_image_path == images_directory_resolved:
            raise ValueError(
                f"COCO annotation refers to image {image_name!r}, which "
                f"resolves to the images directory itself "
                f"({images_directory_resolved}). Expected a path to an "
                "image file."
            )
        if images_directory_resolved not in resolved_image_path.parents:
            raise ValueError(
                f"COCO annotation refers to image {image_name!r}, which "
                f"resolves to {resolved_image_path} — outside the images "
                f"directory {images_directory_resolved}."
            )
        if resolved_image_path.is_dir():
            raise ValueError(
                f"COCO annotation refers to image {image_name!r}, which "
                f"resolves to directory {resolved_image_path}. Expected a "
                "path to an image file."
            )
        image_path = str(resolved_image_path)
        if image_path in annotations:
            raise ValueError(
                f"COCO annotation file contains duplicate entries for image "
                f"{image_name!r}. Each image must appear at most once."
            )

        with_masks = force_masks or any(
            _with_seg_mask(annotation) for annotation in image_annotations
        )
        annotation = coco_annotations_to_detections(
            image_annotations=image_annotations,
            resolution_wh=(image_width, image_height),
            with_masks=with_masks,

View on GitHub (pinned to 7f254d9784)

Solutions

Fix the file_name in the JSON to point at the actual image file (no trailing slash).
Check the converter that produced the JSON for empty-filename or trailing-slash bugs.
Validate entries with Path(name).is_dir() logic removed — ensure the final path ends with an image extension.

Example fix

// before
{"file_name": "train2017/", ...}

// after
{"file_name": "train2017/000000000009.jpg", ...}

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
import json

def find_directory_valued_file_names(annotations_path: str, images_dir: str) -> list[str]:
    """List file_name entries that resolve to an existing directory."""
    data = json.loads(Path(annotations_path).read_text())
    bad = []
    for img in data["images"]:
        p = Path(images_dir, img["file_name"]).resolve()
        if p.is_dir():
            bad.append(img["file_name"])
    return bad

Type guard

def names_image_file(name: str, images_dir: str) -> bool:
    """True when the resolved path exists and is a regular file."""
    p = Path(images_dir, name).resolve()
    return p.is_file()

Try / catch

try:
    sv.DetectionDataset.from_coco(images_directory_path=d, annotations_path=a)
except ValueError as exc:
    if "resolves to directory" in str(exc):
        bad = find_directory_valued_file_names(a, d)
        raise ValueError(f"Fix directory-valued file_name entries: {bad}") from exc
    raise

Prevention

End every file_name with a real image extension (.jpg/.png).
Never build file_name via string concatenation with a possibly-empty filename variable.
Run an is_file() sanity pass over the images array before first load.

When it happens

Trigger: A COCO entry whose file_name ends with '/' or names a directory inside images_directory_path, e.g. file_name="images/" when a subdirectory 'images' exists inside the images root.

Common situations: Concatenation bugs in custom converters (path + '/' + '' when the filename variable is empty); trailing-slash mistakes when building file_name programmatically; dataset trees where a directory shares a name with an expected image.

Related errors

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