{"record":{"id":"9f526191821e7ea3","repo":"roboflow/supervision","slug":"coco-annotation-refers-to-image-image-name-whic-9f5261","errorCode":null,"errorMessage":"COCO annotation refers to image {image_name}, which produces an invalid path: {exc}","messagePattern":"COCO annotation refers to image (.+?), which produces an invalid path: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/coco.py","lineNumber":529,"sourceCode":"    images_directory_resolved = Path(images_directory_path).resolve()\n\n    for coco_image in tqdm(\n        coco_images,\n        total=len(coco_images),\n        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(","sourceCodeStart":511,"sourceCodeEnd":547,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/coco.py#L511-L547","documentation":"Raised by load_coco_annotations when Path(...).resolve() raises OSError or ValueError while resolving the joined image path. This is the wrapper around path resolution for the file_name field: the OS itself rejected the path (e.g. embedded null bytes) before any of the containment checks could run.","triggerScenarios":"A COCO entry whose file_name contains characters that make it unresolvable — classically an embedded NUL byte ('\\0') which raises ValueError in the OS path APIs, or OSError from pathological filesystem state.","commonSituations":"Binary corruption in annotation files; generation from bytes buffers where a NUL leaked into a string; extremely long path components on some platforms.","solutions":["Sanitize file_name fields: strip NUL bytes and control characters (name.replace('\\x00', '')).","Locate the offending entry by printing each file_name with repr() before load; repr exposes hidden characters.","Regenerate the JSON from the original source after fixing the writer."],"exampleFix":"// before\n{\"file_name\": \"img\\u0000.jpg\", ...}\n\n// after\n{\"file_name\": \"img.jpg\", ...}","handlingStrategy":"validation","validationCode":"import json\nfrom pathlib import Path\n\ndef sanitize_coco_file_names(annotations_path: str) -> int:\n    \"\"\"Strip NUL/control characters from file_name; return count fixed.\"\"\"\n    data = json.loads(Path(annotations_path).read_text())\n    fixed = 0\n    for img in data[\"images\"]:\n        clean = \"\".join(ch for ch in img[\"file_name\"] if ch.isprintable())\n        if clean != img[\"file_name\"]:\n            img[\"file_name\"], fixed = clean, fixed + 1\n    Path(annotations_path).write_text(json.dumps(data))\n    return fixed","typeGuard":"def is_resolvable_name(name: str) -> bool:\n    \"\"\"True when the string has no NUL bytes and can be an OS path component.\"\"\"\n    return isinstance(name, str) and \"\\x00\" not in name and name == name.strip()","tryCatchPattern":"try:\n    sv.DetectionDataset.from_coco(images_directory_path=d, annotations_path=a)\nexcept ValueError as exc:\n    if \"invalid path\" in str(exc):\n        sanitize_coco_file_names(a)\n    else:\n        raise","preventionTips":["Write annotation files as UTF-8 text; never splice raw byte buffers into strings.","Debug suspicious entries with repr(file_name) to expose hidden characters.","Checksum-validate downloaded annotation files before use."],"tags":["coco","dataset-load","path-validation","corruption"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}