{"record":{"id":"d9dbeb1b06499f27","repo":"roboflow/supervision","slug":"labelme-annotation-has-an-invalid-imagepath-raw","errorCode":null,"errorMessage":"LabelMe annotation has an invalid 'imagePath' {raw_image_path}.","messagePattern":"LabelMe annotation has an invalid 'imagePath' (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/labelme.py","lineNumber":256,"sourceCode":"    )\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            )\n        with_masks = force_masks or any(\n            shape.get(\"shape_type\") == \"polygon\" for shape in shapes\n        )\n        if with_masks and not (entry.get(\"imageWidth\") and entry.get(\"imageHeight\")):\n            raise ValueError(\n                f\"LabelMe annotation for {image_name!r} requires \"\n                \"'imageWidth' and 'imageHeight' to build masks, but they are \"\n                \"missing or zero.\"\n            )","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/labelme.py#L238-L274","documentation":"Raised when a LabelMe annotation's imagePath resolves to an invalid basename: Path(imagePath).name is empty or the special entries '..' or '.'. This is a hardening check — annotation-controlled path traversal is neutralized by taking the basename only, and degenerate values that would map outside/nowhere are rejected instead of silently producing a broken image path.","triggerScenarios":"DetectionDataset.from_labelme where imagePath is \"/\" (basename empty), \"..\", \".\", or a path ending in a separator such that Path(...).name degenerates.","commonSituations":"Malformed or adversarial JSON values; scripts writing imagePath from an unset variable producing '.'/''; manual edits that leave placeholder paths.","solutions":["Set imagePath in the failing JSON to a real image filename, e.g. \"img_042.png\".","If generated programmatically, validate/normalize the value before writing (must have a non-trivial basename).","Regenerate annotations whose imagePath came from empty template variables."],"exampleFix":"// before\n\"imagePath\": \".\"\n// after\n\"imagePath\": \"img_042.png\"","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef image_path_safe(raw: object) -> bool:\n    \"\"\"imagePath must yield a real, non-special basename.\"\"\"\n    if not isinstance(raw, str) or not raw:\n        return False\n    name = Path(raw).name\n    return bool(name) and name not in ('..', '.')","typeGuard":null,"tryCatchPattern":"try:\n    dataset = sv.DetectionDataset.from_labelme(images_dir, ann_dir)\nexcept ValueError as e:\n    if \"invalid 'imagePath'\" in str(e):\n        raise SystemExit(f'Replace the degenerate imagePath value: {e}') from e\n    raise","preventionTips":["Never write template-derived imagePath values without validation.","Sanitize untrusted annotation JSON before ingestion pipelines.","Prefer basename-only imagePath values in generated files."],"tags":["labelme","dataset","path-traversal","json"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}