{"record":{"id":"7dac7bd92c7c5bef","repo":"roboflow/supervision","slug":"coco-annotation-refers-to-image-image-name-whic","errorCode":null,"errorMessage":"COCO annotation refers to image {image_name}, which resolves to the images directory itself ({images_directory_resolved}). Expected a path to an image file.","messagePattern":"COCO annotation refers to image (.+?), which resolves to the images directory itself \\((.+?)\\)\\. Expected a path to an image file\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/coco.py","lineNumber":534,"sourceCode":"        desc=\"Loading COCO annotations\",\n        disable=not show_progress,\n    ):\n        image_name, image_width, image_height = (\n            coco_image[\"file_name\"],\n            coco_image[\"width\"],\n            coco_image[\"height\"],\n        )\n        image_annotations = coco_annotations_groups.get(coco_image[\"id\"], [])\n        image_path = str(Path(images_directory_path) / Path(image_name))\n        try:\n            resolved_image_path = Path(image_path).resolve()\n        except (OSError, ValueError) as exc:\n            raise ValueError(\n                f\"COCO annotation refers to image {image_name!r}, which \"\n                f\"produces an invalid path: {exc}\"\n            ) from exc\n        if resolved_image_path == images_directory_resolved:\n            raise ValueError(\n                f\"COCO annotation refers to image {image_name!r}, which \"\n                f\"resolves to the images directory itself \"\n                f\"({images_directory_resolved}). Expected a path to an \"\n                \"image file.\"\n            )\n        if images_directory_resolved not in resolved_image_path.parents:\n            raise ValueError(\n                f\"COCO annotation refers to image {image_name!r}, which \"\n                f\"resolves to {resolved_image_path} — outside the images \"\n                f\"directory {images_directory_resolved}.\"\n            )\n        if resolved_image_path.is_dir():\n            raise ValueError(\n                f\"COCO annotation refers to image {image_name!r}, which \"\n                f\"resolves to directory {resolved_image_path}. Expected a \"\n                \"path to an image file.\"\n            )\n        image_path = str(resolved_image_path)","sourceCodeStart":516,"sourceCodeEnd":552,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/coco.py#L516-L552","documentation":"Raised by load_coco_annotations while resolving an image's file_name from the COCO JSON. After joining images_directory_path with the entry's file_name and calling Path.resolve(), the result equals the images directory itself, which means the annotation names no actual image file. This is part of supervision's path-traversal protection on COCO loading.","triggerScenarios":"A COCO JSON entry whose file_name is \"\", \".\", or \"./\" — anything that resolves to the images directory root. load_coco_annotations(images_directory_path=..., annotations_path=...) hits this during its per-image loop.","commonSituations":"Hand-edited or machine-generated COCO files with empty file_name fields; a conversion script that writes os.path.dirname of a path into file_name; corrupted export from another tool.","solutions":["Inspect the images[].file_name entries in the annotations JSON and fix empty/'.' values to real relative filenames.","Regenerate the COCO file with a correct exporter (e.g. supervision's save_coco_annotations).","If the JSON is produced by your own code, assert file_name is a non-empty basename before writing."],"exampleFix":"// before (JSON entry)\n{\"id\": 1, \"file_name\": \"\", \"width\": 640, \"height\": 480}\n\n// after\n{\"id\": 1, \"file_name\": \"000001.jpg\", \"width\": 640, \"height\": 480}","handlingStrategy":"validation","validationCode":"import json\nfrom pathlib import Path\n\ndef validate_coco_file_names(annotations_path: str, images_dir: str) -> None:\n    \"\"\"Fail fast on file_name values that resolve to the images directory.\"\"\"\n    data = json.loads(Path(annotations_path).read_text())\n    imgs_dir = Path(images_dir).resolve()\n    for img in data.get(\"images\", []):\n        name = img.get(\"file_name\", \"\")\n        if not name or Path(imgs_dir, name).resolve() == imgs_dir:\n            raise ValueError(f\"Bad file_name {name!r} on image id {img.get('id')}\")","typeGuard":"def is_valid_coco_file_name(name: object) -> bool:\n    \"\"\"True when file_name is a non-empty string naming a file, not a dir root.\"\"\"\n    return isinstance(name, str) and name.strip() not in (\"\", \".\", \"./\") and not name.endswith(\"/\")","tryCatchPattern":"try:\n    ds = sv.DetectionDataset.from_coco(images_directory_path=d, annotations_path=a)\nexcept ValueError as exc:\n    if \"images directory itself\" in str(exc):\n        raise ValueError(f\"Malformed file_name in {a}; fix empty file_name entries\") from exc\n    raise","preventionTips":["Never write empty file_name values when generating COCO JSON.","Automate a pre-flight scan of file_name fields for '', '.', and trailing slashes.","Generate COCO files with a trusted exporter rather than hand-building dicts."],"tags":["coco","dataset-load","path-validation","data-quality"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}