roboflow/supervision · error · ValueError

Unsupported color lookup strategy: {color_lookup}

Error message

Unsupported color lookup strategy: {color_lookup}

What it means

Raised by resolve_color_idx() in supervision.annotators.utils when the `color_lookup` argument is not a np.ndarray, and not one of the ColorLookup enum values INDEX, CLASS, or TRACK. This is the final fall-through raise after the CLASS and TRACK branches, so it fires only for genuinely unrecognized strategies — typically a typo'd string or a custom enum member.

Source

Thrown at src/supervision/annotators/utils.py:75

        return detection_idx
    elif color_lookup == ColorLookup.CLASS:
        if detections.class_id is None:
            raise ValueError(
                "Could not resolve color by class because "
                "Detections do not have class_id. If using an annotator, "
                "try setting color_lookup to sv.ColorLookup.INDEX or "
                "sv.ColorLookup.TRACK."
            )
        return int(detections.class_id[detection_idx])
    elif color_lookup == ColorLookup.TRACK:
        if detections.tracker_id is None:
            raise ValueError(
                "Could not resolve color by track because "
                "Detections do not have tracker_id. Did you call "
                "tracker.update_with_detections(...) before annotating?"
            )
        return int(detections.tracker_id[detection_idx])
    raise ValueError(f"Unsupported color lookup strategy: {color_lookup}")


def resolve_text_background_xyxy(
    center_coordinates: tuple[int, int],
    text_wh: tuple[int, int],
    position: Position,
) -> tuple[int, int, int, int]:
    """Compute the background box for text anchored at `position`."""
    center_x, center_y = center_coordinates
    text_w, text_h = text_wh

    if position == Position.TOP_LEFT:
        return center_x, center_y - text_h, center_x + text_w, center_y
    elif position == Position.TOP_RIGHT:
        return center_x - text_w, center_y - text_h, center_x, center_y
    elif position == Position.TOP_CENTER:
        return (
            center_x - text_w // 2,

View on GitHub (pinned to 7f254d9784)

Solutions

1. Use the enum: color_lookup=sv.ColorLookup.INDEX / CLASS / TRACK.
2. When loading from config, map strings explicitly: {'INDEX': sv.ColorLookup.INDEX, ...}[raw.upper()].
3. If you need per-detection colors, pass a NumPy int array instead of an enum value.
4. Upgrade supervision if you intended a newly introduced lookup mode.

Example fix

// before
annotator = sv.BoxAnnotator(color_lookup='index')

// after
annotator = sv.BoxAnnotator(color_lookup=sv.ColorLookup.INDEX)

valid = set(sv.ColorLookup.list())
assert color_lookup in valid or isinstance(color_lookup, np.ndarray), color_lookup

def is_valid_color_lookup(value: object) -> bool:
    return isinstance(value, np.ndarray) or (
        isinstance(value, sv.ColorLookup) and value.value in sv.ColorLookup.list()
    )

try:
    annotator.annotate(scene, detections)
except ValueError as e:
    if 'color lookup' in str(e):
        annotator.color_lookup = sv.ColorLookup.INDEX
    raise

When it happens

Trigger: Passing color_lookup='index' (lowercase string) instead of sv.ColorLookup.INDEX; passing a custom ColorLookup subclass member; passing an int or None where the enum is expected.

Common situations: Constructing annotators from YAML/JSON config where the string is not converted to the enum; newer supervision versions adding enum members unknown to older code paths; copy-paste of raw strings from docs.

Related errors

• Unsupported position: {position}
• max_line_length must be a positive integer
• roundness attribute must be float between (0, 1.0]
• Invalid vlm value: {vlm}. Must be one of {[e.value for e in
• Invalid value type: {type(value)}. Must be an instance of {c

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/5625313224fdd5a6. Report an issue: GitHub.