{"record":{"id":"5e0bda93dcb56ab6","repo":"roboflow/supervision","slug":"createml-annotation-entry-is-missing-the-required","errorCode":null,"errorMessage":"CreateML annotation entry is missing the required 'image' key: {entry}","messagePattern":"CreateML annotation entry is missing the required 'image' key: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/createml.py","lineNumber":203,"sourceCode":"            }\n        )\n    except (KeyError, TypeError) as exc:\n        raise ValueError(\n            f\"Malformed CreateML annotation entry \"\n            f\"(missing or non-string 'label'): {exc}\"\n        ) from exc\n    class_to_index = {class_name: index for index, class_name in enumerate(classes)}\n\n    image_paths: list[str] = []\n    annotations: dict[str, Detections] = {}\n    for entry in tqdm(\n        createml_data,\n        desc=\"Loading CreateML annotations\",\n        disable=not show_progress,\n    ):\n        image_name = entry.get(\"image\")\n        if image_name is None:\n            raise ValueError(\n                f\"CreateML annotation entry is missing the required 'image' key: \"\n                f\"{entry!r}\"\n            )\n        image_path = _resolve_image_path(\n            images_directory_path=images_directory_path, image_name=image_name\n        )\n        if image_path in annotations:\n            raise ValueError(\n                f\"CreateML annotation file contains duplicate entries for image \"\n                f\"{image_name!r}. Each image must appear at most once.\"\n            )\n        annotations[image_path] = createml_annotations_to_detections(\n            image_annotations=entry.get(\"annotations\") or [],\n            class_to_index=class_to_index,\n        )\n        image_paths.append(image_path)\n\n    return classes, image_paths, annotations","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/createml.py#L185-L221","documentation":"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.","triggerScenarios":"A CreateML JSON entry like {\"annotations\": [...]} with no \"image\" field, or where the key is misspelled ('filename', 'file_name', 'path').","commonSituations":"Schema drift between CreateML exporters; hand-written entries; renaming keys during a format conversion and missing some.","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."],"exampleFix":"// before\n{\"annotations\": [{\"label\": \"dog\", \"coordinates\": {...}}]}\n\n// after\n{\"image\": \"a.jpg\", \"annotations\": [{\"label\": \"dog\", \"coordinates\": {...}}]}","handlingStrategy":"validation","validationCode":"import json\nfrom pathlib import Path\n\ndef validate_createml_entries(annotations_path: str) -> None:\n    \"\"\"Fail fast if any entry lacks a truthy 'image' string.\"\"\"\n    entries = json.loads(Path(annotations_path).read_text())\n    for e in entries:\n        if not isinstance(e.get(\"image\"), str) or not e[\"image\"]:\n            raise ValueError(f\"Entry missing 'image': {e!r}\")","typeGuard":"def is_valid_createml_entry(entry: object) -> bool:\n    \"\"\"True when entry is a dict with a non-empty 'image' string.\"\"\"\n    return isinstance(entry, dict) and isinstance(entry.get(\"image\"), str) and bool(entry[\"image\"].strip())","tryCatchPattern":"try:\n    sv.DetectionDataset.from_createml(images_directory_path=d, annotations_path=a)\nexcept ValueError as exc:\n    if \"missing the required 'image' key\" in str(exc):\n        validate_createml_entries(a)  # pinpoint all offenders\n    raise","preventionTips":["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'."],"tags":["createml","dataset-load","schema","missing-key"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}