roboflow/supervision · error · ValueError

Number of labels ({len(resolved)}) must match number of key

Error message

Number of labels ({len(resolved)}) must match number of key points ({points_count}).

What it means

Raised by the CI helper script .github/scripts/verify_clean_wheel.py when a built supervision wheel's METADATA still lists a Requires-Dist entry containing 'opencv' (case-insensitive). supervision has moved OpenCV to an optional dependency, so the wheel must not hard-require any opencv runtime; this check enforces that packaging invariant before publishing. It is a release-infrastructure assertion, not a runtime error library users normally see.

Source

Thrown at src/supervision/key_points/annotators.py:975

        """Return the label list for a single instance."""
        if labels is None:
            return [str(j) for j in range(points_count)]

        resolved: list[str]
        if isinstance(labels, dict):
            if class_id is None:
                raise ValueError(
                    "labels is a dict but class_id is None; "
                    "KeyPoints must have class_id set."
                )
            if class_id not in labels:
                raise ValueError(f"No labels defined for class_id={class_id}.")
            resolved = labels[class_id]
        else:
            resolved = labels

        if len(resolved) != points_count:
            raise ValueError(
                f"Number of labels ({len(resolved)}) must match "
                f"number of key points ({points_count})."
            )
        return resolved

    @staticmethod
    def _resolve_color_list(
        colors: Color | list[Color],
        points_count: int,
    ) -> list[Color]:
        """Return a per-keypoint color list for a single instance."""
        if isinstance(colors, list):
            if len(colors) != points_count:
                raise ValueError(
                    f"Number of colors ({len(colors)}) must match "
                    f"number of key points ({points_count})."
                )
            return colors

View on GitHub (pinned to 7f254d9784)

Solutions

Open the wheel's *.dist-info/METADATA and confirm which Requires-Dist line contains 'opencv'.
Move the opencv dependency to an optional extra (e.g. [project.optional-dependencies]) or the appropriate dev/contrib group in pyproject.toml, matching supervision's packaging policy.
Rebuild the wheel from a clean checkout and re-run the verification script.
If the requirement comes from a generated lock/requirements file, regenerate it from pyproject.toml rather than hand-editing.

Example fix

# before (pyproject.toml)
[project]
dependencies = ["numpy", "opencv-python", "pyav"]

# after
[project]
dependencies = ["numpy", "pyav"]
[project.optional-dependencies]
opencv = ["opencv-python-headless"]

Defensive patterns

Strategy: validation

Validate before calling

# In CI, before verify_clean_wheel.py:
import zipfile, pathlib

def wheel_has_no_opencv_requirement(wheel: pathlib.Path) -> bool:
    with zipfile.ZipFile(wheel) as z:
        meta = next(n for n in z.namelist() if n.endswith('/METADATA'))
        text = z.read(meta).decode()
    return not any(
        line.startswith('Requires-Dist:') and 'opencv' in line.lower()
        for line in text.splitlines()
    )

Prevention

Keep opencv strictly out of [project].dependencies; it belongs only where project policy allows (and per this repo, not even as an extra).
Run the wheel verification script in CI before any publish step so packaging drift fails the build.
After any dependency-metadata change, build the wheel locally and inspect *.dist-info/METADATA Requires-Dist lines.

When it happens

Trigger: Building the wheel while pyproject still declares opencv-python (or opencv-python-headless / opencv-contrib-python) in core dependencies; running verify_clean_wheel.py against a wheel built from a branch that re-added the runtime requirement; a build tool pulling in a stale lockfile that reinstates the requirement.

Common situations: Contributors adding opencv back to install_requires to fix a local import error; release workflows building from a dirty merge state; dependency-management tools (poetry/uv/pip-compile) regenerating metadata with the opencv requirement included.

Related errors

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