facebookresearch/detectron2 · error · KeyError

Encountered category_id={annotation_category_id} but this id

Error message

Encountered category_id={annotation_category_id} but this id does not exist in 'categories' of the json file.

What it means

When a non-contiguous category_id remapping (id_map) is needed, load_coco_json looks up each annotation's category_id in a dict built from the json's 'categories'. If an annotation references an id absent from 'categories', the KeyError is re-raised with this message.

Source

Thrown at detectron2/data/datasets/coco.py:216

            keypts = anno.get("keypoints", None)
            if keypts:  # list[int]
                for idx, v in enumerate(keypts):
                    if idx % 3 != 2:
                        # COCO's segmentation coordinates are floating points in [0, H or W],
                        # but keypoint coordinates are integers in [0, H-1 or W-1]
                        # Therefore we assume the coordinates are "pixel indices" and
                        # add 0.5 to convert to floating point coordinates.
                        keypts[idx] = v + 0.5
                obj["keypoints"] = keypts

            obj["bbox_mode"] = BoxMode.XYWH_ABS
            if id_map:
                annotation_category_id = obj["category_id"]
                try:
                    obj["category_id"] = id_map[annotation_category_id]
                except KeyError as e:
                    raise KeyError(
                        f"Encountered category_id={annotation_category_id} "
                        "but this id does not exist in 'categories' of the json file."
                    ) from e
            objs.append(obj)
        record["annotations"] = objs
        dataset_dicts.append(record)

    if num_instances_without_valid_segmentation > 0:
        logger.warning(
            "Filtered out {} instances without valid segmentation. ".format(
                num_instances_without_valid_segmentation
            )
            + "There might be issues in your dataset generation process.  Please "
            "check https://detectron2.readthedocs.io/en/latest/tutorials/datasets.html carefully"
        )
    return dataset_dicts

View on GitHub (pinned to a2f4a8771a)

Solutions

1. Rebuild categories to cover every category_id used in annotations (make ids 1..K contiguous, no 0)
2. Validate ids beforehand: set(a['category_id'] for a in anns) - set(c['id'] for c in cats) must be empty
3. Fix the converter/exporter to write consistent category ids

Example fix

# before
# categories ids [1,2] but annotations contain category_id=3
# after
missing = {a['category_id'] for a in d['annotations']} - {c['id'] for c in d['categories']}
assert not missing, f"annotations reference unknown category ids: {missing}"

used = {a['category_id'] for a in d['annotations']}
declared = {c['id'] for c in d['categories']}
missing = used - declared
assert not missing, f'annotations reference undeclared category ids: {missing}'

def categories_complete(d) -> bool:
    declared = {c['id'] for c in d['categories']}
    return all(a['category_id'] in declared for a in d['annotations'])

try:
    d = load_coco_json(json_file, img_root, 'mydata')
except KeyError as e:
    # re-map or drop offending annotations, then retry
    ...

When it happens

Trigger: Loading COCO data with annotation['category_id'] not present among the ids in the json's categories section — e.g. category ids 0..k used in annotations but categories listing 1..k+1, or stale annotations from a later schema merged into an older categories list.

Common situations: COCO jsons with category_id starting at 0 (COCO requires 1-based); merging annotation files from different taxonomy versions; converters that forget to emit some categories.

Related errors

• No built-in metadata for dataset {}
• One annotation of image {image_id} contains empty 'bbox' val
• Cannot match one checkpoint key to multiple keys in the mode
• Class with @configurable must have a 'from_config' classmeth
• {name} must take 'cfg' as the first argument!

AI-assisted analysis of facebookresearch/detectron2@a2f4a8771a (2026-08-27). Data as JSON: /api/errors/8fc9554baad4a9dc. Report an issue: GitHub.