roboflow/supervision · error · ValueError

CreateML annotation entry is missing the required 'image' ke

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.

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)

Solutions

  1. Add the "image" key with the relative image filename to each offending entry.
  2. If your file uses a different key name, rewrite it: entry['image'] = entry.pop('file_name').
  3. 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

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.