roboflow/supervision · error · ValueError

CreateML annotation entry is missing the required 'image'…

Error message

CreateML annotation entry is missing the required 'image' key: {entry}

What it means

Raised by load_createml_annotations when an entry dict has no 'image' key (entry.get("image") returns None). Every CreateML entry must carry an image reference; the full offending entry is echoed in the message to make locating it easy.

Solutions

Add the "image" key with the relative image filename to each offending entry.
If your file uses a different key name, rewrite it: entry['image'] = entry.pop('file_name').
Pre-validate the JSON: every top-level entry must contain a truthy 'image' string.

Example fix

// before
{"annotations": [{"label": "dog", "coordinates": {...}}]}

// after
{"image": "a.jpg", "annotations": [{"label": "dog", "coordinates": {...}}]}

Defensive patterns

Strategy: validation

Validate before calling

import json
from pathlib import Path

def validate_createml_entries(annotations_path: str) -> None:
    """Fail fast if any entry lacks a truthy 'image' string."""
    entries = json.loads(Path(annotations_path).read_text())
    for e in entries:
        if not isinstance(e.get("image"), str) or not e["image"]:
            raise ValueError(f"Entry missing 'image': {e!r}")

Type guard

def is_valid_createml_entry(entry: object) -> bool:
    """True when entry is a dict with a non-empty 'image' string."""
    return isinstance(entry, dict) and isinstance(entry.get("image"), str) and bool(entry["image"].strip())

Try / catch

try:
    sv.DetectionDataset.from_createml(images_directory_path=d, annotations_path=a)
except ValueError as exc:
    if "missing the required 'image' key" in str(exc):
        validate_createml_entries(a)  # pinpoint all offenders
    raise

Prevention

Use the exact key 'image' (not 'file_name'/'filename') in CreateML entries.
Add a JSON schema or small validator to your data-ingest step.
Log the full entry when your own writer produces one without 'image'.

When it happens

Trigger: A CreateML JSON entry like {"annotations": [...]} with no "image" field, or where the key is misspelled ('filename', 'file_name', 'path').

Common situations: Schema drift between CreateML exporters; hand-written entries; renaming keys during a format conversion and missing some.

Related errors

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

Appendix: source

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

            }
        )
    except (KeyError, TypeError) as exc:
        raise ValueError(
            f"Malformed CreateML annotation entry "
            f"(missing or non-string 'label'): {exc}"
        ) from exc
    class_to_index = {class_name: index for index, class_name in enumerate(classes)}

    image_paths: list[str] = []
    annotations: dict[str, Detections] = {}
    for entry in tqdm(
        createml_data,
        desc="Loading CreateML annotations",
        disable=not show_progress,
    ):
        image_name = entry.get("image")
        if image_name is None:
            raise ValueError(
                f"CreateML annotation entry is missing the required 'image' key: "
                f"{entry!r}"
            )
        image_path = _resolve_image_path(
            images_directory_path=images_directory_path, image_name=image_name
        )
        if image_path in annotations:
            raise ValueError(
                f"CreateML annotation file contains duplicate entries for image "
                f"{image_name!r}. Each image must appear at most once."
            )
        annotations[image_path] = createml_annotations_to_detections(
            image_annotations=entry.get("annotations") or [],
            class_to_index=class_to_index,
        )
        image_paths.append(image_path)

    return classes, image_paths, annotations

View on GitHub (pinned to 7f254d9784)