{"record":{"id":"792d3d15257914a8","repo":"roboflow/supervision","slug":"coco-annotation-refers-to-image-image-name-whic-792d3d","errorCode":null,"errorMessage":"COCO annotation refers to image {image_name}, which resolves to directory {resolved_image_path}. Expected a path to an image file.","messagePattern":"COCO annotation refers to image (.+?), which resolves to directory (.+?)\\. Expected a path to an image file\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/coco.py","lineNumber":547,"sourceCode":"            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)\n        if image_path in annotations:\n            raise ValueError(\n                f\"COCO annotation file contains duplicate entries for image \"\n                f\"{image_name!r}. Each image must appear at most once.\"\n            )\n\n        with_masks = force_masks or any(\n            _with_seg_mask(annotation) for annotation in image_annotations\n        )\n        annotation = coco_annotations_to_detections(\n            image_annotations=image_annotations,\n            resolution_wh=(image_width, image_height),\n            with_masks=with_masks,","sourceCodeStart":529,"sourceCodeEnd":565,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/coco.py#L529-L565","documentation":"Raised by load_coco_annotations when the resolved path for a COCO image entry is an existing directory rather than a file. The loader accepts subdirectories in file_name, but the final component must name an image file; resolving to a directory means the annotation is unusable.","triggerScenarios":"A COCO entry whose file_name ends with '/' or names a directory inside images_directory_path, e.g. file_name=\"images/\" when a subdirectory 'images' exists inside the images root.","commonSituations":"Concatenation bugs in custom converters (path + '/' + '' when the filename variable is empty); trailing-slash mistakes when building file_name programmatically; dataset trees where a directory shares a name with an expected image.","solutions":["Fix the file_name in the JSON to point at the actual image file (no trailing slash).","Check the converter that produced the JSON for empty-filename or trailing-slash bugs.","Validate entries with Path(name).is_dir() logic removed — ensure the final path ends with an image extension."],"exampleFix":"// before\n{\"file_name\": \"train2017/\", ...}\n\n// after\n{\"file_name\": \"train2017/000000000009.jpg\", ...}","handlingStrategy":"validation","validationCode":"from pathlib import Path\nimport json\n\ndef find_directory_valued_file_names(annotations_path: str, images_dir: str) -> list[str]:\n    \"\"\"List file_name entries that resolve to an existing directory.\"\"\"\n    data = json.loads(Path(annotations_path).read_text())\n    bad = []\n    for img in data[\"images\"]:\n        p = Path(images_dir, img[\"file_name\"]).resolve()\n        if p.is_dir():\n            bad.append(img[\"file_name\"])\n    return bad","typeGuard":"def names_image_file(name: str, images_dir: str) -> bool:\n    \"\"\"True when the resolved path exists and is a regular file.\"\"\"\n    p = Path(images_dir, name).resolve()\n    return p.is_file()","tryCatchPattern":"try:\n    sv.DetectionDataset.from_coco(images_directory_path=d, annotations_path=a)\nexcept ValueError as exc:\n    if \"resolves to directory\" in str(exc):\n        bad = find_directory_valued_file_names(a, d)\n        raise ValueError(f\"Fix directory-valued file_name entries: {bad}\") from exc\n    raise","preventionTips":["End every file_name with a real image extension (.jpg/.png).","Never build file_name via string concatenation with a possibly-empty filename variable.","Run an is_file() sanity pass over the images array before first load."],"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"}