roboflow/supervision · error · ValueError

CreateML annotation refers to image {image_name}, which prod

Error message

CreateML annotation refers to image {image_name}, which produces an invalid path: {exc}

What it means

Raised by _resolve_image_path in the CreateML loader when Path.resolve() raises OSError or ValueError while resolving the joined image path. It wraps the OS-level resolution failure with the offending image name, before the containment checks run.

Source

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

    from supervision.dataset.core import DetectionDataset

CreateMLDict = dict[str, Any]


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 "

View on GitHub (pinned to 7f254d9784)

Solutions

Print repr(entry['image']) to find hidden characters, then strip NULs and control chars.
Repair the JSON: sanitize each image field to a plain ASCII/UTF-8 filename.
Regenerate the file from source data.

Example fix

// before
{"image": "img\u0000.jpg"}

// after
{"image": "img.jpg"}

Defensive patterns

Strategy: validation

Validate before calling

import json
from pathlib import Path

def sanitize_createml_images(annotations_path: str) -> int:
    """Strip NUL/control characters from 'image' fields; return count fixed."""
    entries = json.loads(Path(annotations_path).read_text())
    fixed = 0
    for e in entries:
        clean = "".join(ch for ch in e["image"] if ch.isprintable())
        if clean != e["image"]:
            e["image"], fixed = clean, fixed + 1
    Path(annotations_path).write_text(json.dumps(entries))
    return fixed

Type guard

def is_resolvable_createml_image(name: str) -> bool:
    """True when the string contains no NUL bytes or control characters."""
    return isinstance(name, str) and all(ch.isprintable() for ch in name)

Try / catch

try:
    sv.DetectionDataset.from_createml(images_directory_path=d, annotations_path=a)
except ValueError as exc:
    if "invalid path" in str(exc):
        sanitize_createml_images(a)
    else:
        raise

Prevention

Inspect odd values with repr() to reveal embedded control characters.
Validate downloaded annotation files with a checksum before loading.
Keep annotation generation purely text-based (UTF-8 JSON dumps).

When it happens

Trigger: A CreateML entry whose image string contains an embedded NUL byte (ValueError from OS path APIs) or triggers an OSError during resolution on the host filesystem.

Common situations: Corrupted or binary-mangled annotation files; strings built from byte buffers with stray NULs; platform-specific path length limits.

Related errors

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