roboflow/supervision · error · ValueError

CreateML annotation refers to image {image_name}, which reso

Error message

CreateML annotation refers to image {image_name}, which resolves to the images directory itself ({images_directory_resolved}). Expected a path to an image file.

What it means

Raised by _resolve_image_path in the CreateML loader when the entry's image field resolves to the images directory itself. The CreateML loader mirrors the COCO loader's path protection: image must name a real file inside images_directory_path, not the directory.

Source

Thrown at src/supervision/dataset/formats/createml.py:37

def _resolve_image_path(images_directory_path: str, image_name: str) -> str:
    """Resolve and validate an image path against the images directory.

    Rejects annotations whose ``image`` field escapes ``images_directory_path``
    (via ``..`` traversal, an absolute path, or a symlink pointing outside),
    mirroring the protection used by the COCO loader. Returns the canonical
    resolved path so aliases collapse to a single dataset entry.
    """
    images_directory_resolved = Path(images_directory_path).resolve()
    image_path = Path(images_directory_path) / Path(image_name)
    try:
        resolved_image_path = image_path.resolve()
    except (OSError, ValueError) as exc:
        raise ValueError(
            f"CreateML 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"CreateML 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"CreateML 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"CreateML annotation refers to image {image_name!r}, which "
            f"resolves to directory {resolved_image_path}. Expected a path "
            "to an image file."
        )
    return str(resolved_image_path)

View on GitHub (pinned to 7f254d9784)

Solutions

Fix the empty/'.' image values in the CreateML JSON to real filenames.
Validate entries before loading: assert entry.get('image') not in (None, '', '.').
Regenerate the annotation file with a correct converter.

Example fix

// before
{"image": "", "annotations": [...]}

// after
{"image": "photo1.jpg", "annotations": [...]}

Defensive patterns

Strategy: validation

Validate before calling

import json
from pathlib import Path

def validate_createml_images(annotations_path: str, images_dir: str) -> None:
    """Fail fast on image fields that resolve to the images directory."""
    entries = json.loads(Path(annotations_path).read_text())
    root = Path(images_dir).resolve()
    for e in entries:
        name = e.get("image", "")
        if not name or Path(root, name).resolve() == root:
            raise ValueError(f"Bad 'image' value {name!r} in entry {e!r}")

Type guard

def is_valid_createml_image_field(name: object) -> bool:
    """True when image is a non-empty string naming a file, not the dir root."""
    return isinstance(name, str) and name.strip() not in ("", ".", "./") and not name.endswith("/")

Try / catch

try:
    sv.DetectionDataset.from_createml(images_directory_path=d, annotations_path=a)
except ValueError as exc:
    if "images directory itself" in str(exc):
        raise ValueError(f"Fix empty 'image' fields in {a}") from exc
    raise

Prevention

Every CreateML entry must carry a real relative filename in 'image'.
Guard your converter: assert entry['image'] before writing JSON.
Reuse a pre-flight validator on any hand-edited annotation file.

When it happens

Trigger: A CreateML JSON entry with "image": "", ".", or "./" — values that resolve to the images directory root. Hit when calling sv.dataset.formats.createml.load_createml_annotations (or DetectionDataset.from_createml).

Common situations: CreateML JSON produced by a script with an empty filename variable; hand-written annotation files; porting COCO-style data where the file_name field was left blank.

Related errors

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