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 {resolved_image_path} — outside the images directory {images_directory_resolved}.

What it means

Raised by load_coco_annotations when the resolved image path is not under the resolved images directory (images_directory_resolved is not among resolved_image_path.parents). This blocks absolute file_name values and '..' traversal in COCO annotations, keeping loads confined to the directory you passed.

Source

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

        )
        image_annotations = coco_annotations_groups.get(coco_image["id"], [])
        image_path = str(Path(images_directory_path) / Path(image_name))
        try:
            resolved_image_path = Path(image_path).resolve()
        except (OSError, ValueError) as exc:
            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(

View on GitHub (pinned to 7f254d9784)

Solutions

  1. Rewrite file_name values in the JSON to bare relative filenames (e.g. 'img.jpg' or 'subdir/img.jpg').
  2. Verify images_directory_path actually points to the directory containing the images referenced by the file.
  3. One-liner fixup: json load, set img['file_name'] = os.path.basename(img['file_name']) for each entry, dump back.

Example fix

// before (JSON entry)
{"file_name": "/home/user/datasets/coco/train/images/000001.jpg", ...}

// after
{"file_name": "000001.jpg", ...}
Defensive patterns

Strategy: validation

Validate before calling

import json, os
from pathlib import Path

def normalize_coco_file_names(annotations_path: str, images_dir: str) -> None:
    """Rewrite absolute/traversal file_name values to safe relative names."""
    data = json.loads(Path(annotations_path).read_text())
    imgs_dir = Path(images_dir).resolve()
    for img in data["images"]:
        if os.path.isabs(img["file_name"]) or ".." in Path(img["file_name"]).parts:
            img["file_name"] = os.path.basename(img["file_name"])
    Path(annotations_path).write_text(json.dumps(data))

Type guard

def is_confined_coco_file_name(name: str, images_dir: str) -> bool:
    """True when the joined resolved path stays strictly inside images_dir."""
    root = Path(images_dir).resolve()
    return root in (root / name).resolve().parents

Try / catch

try:
    sv.DetectionDataset.from_coco(images_directory_path=d, annotations_path=a)
except ValueError as exc:
    if "outside the images directory" in str(exc):
        normalize_coco_file_names(a, d)  # strip absolute/traversal names, then retry
    else:
        raise

Prevention

When it happens

Trigger: A COCO entry with file_name="/data/images/img.jpg" (absolute path — joining then resolving yields the absolute path outside the images dir) or file_name="../../elsewhere/img.jpg". Also triggered when the images directory itself is a symlink and file_name escapes it after resolution.

Common situations: COCO files generated on another machine with absolute paths baked in; annotation files from tools that store full paths instead of relative names; passing the wrong images_directory_path that does not actually contain the images.

Related errors

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