{"record":{"id":"bc06d8cd0a72bfcf","repo":"roboflow/supervision","slug":"class-class-name-not-found-in-target-classes-so","errorCode":null,"errorMessage":"Class {class_name} not found in target classes. source_classes must be a subset of target_classes.","messagePattern":"Class (.+?) not found in target classes\\. source_classes must be a subset of target_classes\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/utils.py","lineNumber":113,"sourceCode":"def merge_class_lists(class_lists: list[list[str]]) -> list[str]:\n    unique_classes = set()\n\n    for class_list in class_lists:\n        for class_name in class_list:\n            unique_classes.add(class_name)\n\n    return sorted(list(unique_classes))\n\n\ndef build_class_index_mapping(\n    source_classes: list[str], target_classes: list[str]\n) -> dict[int, int]:\n    \"\"\"Returns the index map of source classes -> target classes.\"\"\"\n    index_mapping = {}\n\n    for i, class_name in enumerate(source_classes):\n        if class_name not in target_classes:\n            raise ValueError(\n                f\"Class {class_name} not found in target classes. \"\n                \"source_classes must be a subset of target_classes.\"\n            )\n        corresponding_index = target_classes.index(class_name)\n        index_mapping[i] = corresponding_index\n\n    return index_mapping\n\n\ndef map_detections_class_id(\n    source_to_target_mapping: dict[int, int], detections: Detections\n) -> Detections:\n    if detections.class_id is None:\n        raise ValueError(\"Detections must have class_id attribute.\")\n    if set(np.unique(detections.class_id)) - set(source_to_target_mapping.keys()):\n        raise ValueError(\n            \"Detections class_id must be a subset of source_to_target_mapping keys.\"\n        )","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/utils.py#L95-L131","documentation":"Raised by build_class_index_mapping() when a class name in source_classes does not appear in target_classes. The function produces a source-index → target-index dict used to re-index annotations between datasets; a source class absent from the target list has no valid target index, so it fails with a subset requirement message.","triggerScenarios":"Calling build_class_index_mapping(source_classes=['cat','dog','person'], target_classes=['cat','dog']) — 'person' is not in target. Common when merging two detection datasets whose class lists were collected independently.","commonSituations":"Using DetectionDataset.merge() or as_yolo/as_voc exports where classes differ across datasets; target classes derived from one dataset's annotations while the source has extra labels; case/whitespace differences in class names ('Cat' vs 'cat').","solutions":["Build the target class list with supervision.merge_class_lists() (used internally by merge) so it is the union of all datasets' classes.","Normalize class name strings (strip/casefold) before comparing if names differ only by case or whitespace.","Drop or rename the extra source classes that the target genuinely should not contain."],"exampleFix":"// before\nmapping = build_class_index_mapping(src_ds.classes, tgt_ds.classes)  # tgt missing classes\n\n// after\nfrom supervision.dataset.utils import merge_class_lists\nmerged_classes = merge_class_lists([src_ds.classes, tgt_ds.classes])\nmapping = build_class_index_mapping(src_ds.classes, merged_classes)","handlingStrategy":"validation","validationCode":"missing = [c for c in source_classes if c not in target_classes]\nif missing:\n    target_classes = merge_class_lists([target_classes, source_classes])\nmapping = build_class_index_mapping(source_classes, target_classes)","typeGuard":"def is_subset(source: list[str], target: list[str]) -> bool:\n    return set(source) <= set(target)","tryCatchPattern":null,"preventionTips":["Always build the target class list with merge_class_lists before mapping.","Normalize class-name strings (strip, casefold) when combining datasets from different sources.","Assert set(source) <= set(target) in dataset-merge tests."],"tags":["dataset","class-mapping","merge","validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}