{"record":{"id":"efc00cf9bbec580f","repo":"roboflow/supervision","slug":"a-labelme-annotation-file-is-missing-the-required","errorCode":null,"errorMessage":"A LabelMe annotation file is missing the required 'imagePath' field or it is empty.","messagePattern":"A LabelMe annotation file is missing the required 'imagePath' field or it is empty\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/labelme.py","lineNumber":247,"sourceCode":"\n    classes = sorted(\n        {\n            shape.get(\"label\")\n            for entry in entries\n            for shape in entry.get(\"shapes\", [])\n            if shape.get(\"shape_type\") in SUPPORTED_SHAPE_TYPES\n        }\n        - {None}\n    )\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 entries:\n        shapes = entry.get(\"shapes\", [])\n        raw_image_path = entry.get(\"imagePath\")\n        if not raw_image_path:\n            raise ValueError(\n                \"A LabelMe annotation file is missing the required \"\n                \"'imagePath' field or it is empty.\"\n            )\n        # ponytail: basename-only, no symlink resolution — images_directory_path\n        # is trusted; annotation-driven traversal is neutralised by .name.\n        # See createml._resolve_image_path for the full .resolve()+parents pattern.\n        image_name = Path(raw_image_path).name\n        if not image_name or image_name in (\"..\", \".\"):\n            raise ValueError(\n                f\"LabelMe annotation has an invalid 'imagePath' {raw_image_path!r}.\"\n            )\n        image_path = str(Path(images_directory_path) / image_name)\n        if image_path in annotations:\n            raise ValueError(\n                f\"Duplicate image basename {image_name!r} resolved from multiple \"\n                \"annotation files. All annotation files must reference unique \"\n                \"image basenames.\"\n            )","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/labelme.py#L229-L265","documentation":"Raised while loading a LabelMe dataset when an annotation file's 'imagePath' field is missing, null, or an empty string. supervision needs imagePath to link the annotation to an image file in images_directory_path (it uses only the basename), so an absent value makes the pairing impossible and fails with this generic message.","triggerScenarios":"DetectionDataset.from_labelme where a .json entry has no 'imagePath' key, imagePath: null, or imagePath: \"\" — typical of programmatically generated annotations that skip the field.","commonSituations":"Annotations created by export scripts that only write shapes; LabelMe files edited to remove metadata; schema drift from other tools that use a different key name (e.g. 'image_path').","solutions":["Open the failing .json and add \"imagePath\": \"<image file name>\" matching a file in images_directory_path.","If your generator uses a different key, rename it to imagePath when writing.","If imagePath is a relative path with directories, that is fine — supervision takes the basename."],"exampleFix":"// before\n{\"shapes\": [...], \"imageHeight\": 480}\n// after\n{\"shapes\": [...], \"imagePath\": \"photo_01.jpg\", \"imageHeight\": 480}","handlingStrategy":"validation","validationCode":"def has_image_path(entry: dict) -> bool:\n    \"\"\"LabelMe entry must carry a non-empty imagePath string.\"\"\"\n    return bool(entry.get('imagePath'))","typeGuard":null,"tryCatchPattern":"try:\n    dataset = sv.DetectionDataset.from_labelme(images_dir, ann_dir)\nexcept ValueError as e:\n    if 'imagePath' in str(e):\n        raise SystemExit(f'Add \"imagePath\" to the failing LabelMe JSON: {e}') from e\n    raise","preventionTips":["Write imagePath whenever generating LabelMe JSON.","Keep the official LabelMe metadata block (imagePath/imageWidth/imageHeight) intact.","Automate checks: every .json's imagePath basename exists in the images dir."],"tags":["labelme","dataset","json","annotation-format"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}