roboflow/supervision · error · ValueError

The number of icon paths provided ({len(icon_path)}) does no

Error message

The number of icon paths provided ({len(icon_path)}) does not match the number of detections ({len(detections)}). Either provide a single icon path or one for each detection.

What it means

Raised by `IconAnnotator.annotate` when `icon_path` is a list whose length differs from the number of detections. The API accepts either one path (applied to all detections) or exactly one path per detection; any other count is ambiguous and rejected before drawing.

Source

Thrown at src/supervision/annotators/core.py:2005

            available_icons = ["roboflow.png", "lenny.png"]
            icon_paths = [np.random.choice(available_icons) for _ in detections]

            icon_annotator = sv.IconAnnotator()
            annotated_frame = icon_annotator.annotate(
                scene=image.copy(),
                detections=detections,
                icon_path=icon_paths
            )
            ```

        ![icon-annotator-example](https://media.roboflow.com/
        supervision-annotator-examples/icon-annotator-example.png)
        """
        if not isinstance(scene, np.ndarray):
            return scene
        if isinstance(icon_path, list) and len(icon_path) != len(detections):
            raise ValueError(
                f"The number of icon paths provided ({len(icon_path)}) does not match "
                f"the number of detections ({len(detections)}). Either provide a single"
                f" icon path or one for each detection."
            )

        xy: npt.NDArray[np.int32] = detections.get_anchors_coordinates(
            anchor=self.position
        ).astype(int)

        for detection_idx in range(len(detections)):
            current_path = (
                icon_path if isinstance(icon_path, str) else icon_path[detection_idx]
            )
            if current_path == "":
                continue
            icon = self._load_icon(current_path)
            icon_h, icon_w = icon.shape[:2]

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass a single path string when every detection should get the same icon.
2. Otherwise rebuild the list per frame so `len(icon_path) == len(detections)`, deriving entries from `detections.class_id`.
3. Apply the same filter mask to the icon list that you applied to the detections.

Example fix

# before
icons = ["dog.png", "cat.png", "bird.png"]
detections = detections[detections.confidence > 0.5]  # len changed
annotator.annotate(scene, detections, icon_path=icons)  # ValueError

# after
icon_by_class = {0: "dog.png", 1: "cat.png", 2: "bird.png"}
icons = [icon_by_class[c] for c in detections.class_id]
annotator.annotate(scene, detections, icon_path=icons)

if isinstance(icon_path, list):
    assert len(icon_path) == len(detections), (
        f"{len(icon_path)} icons for {len(detections)} detections"
    )

When it happens

Trigger: Calling `annotate(scene, detections, icon_path=["a.png", "b.png"])` with 5 detections; filtering detections after building the per-detection icon list; passing a list of paths for multi-class icon sets while detections include all classes.

Common situations: Per-class icon lists sized by number of classes rather than number of detections; detections changing length between frames (tracking/filtering) while the icon list is static; empty detections combined with a non-empty icon list.

Related errors

• Length of color lookup {len(color_lookup)} does not match le
• '{CLASS_NAME_DATA_FIELD}' has {len(class_names)} entries but
• 'class_id' has {len(detections.class_id)} entries but detect
• Error: Couldn't load the icon image from {icon_path}
• The length of custom_values must match the number of detecti

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