roboflow/supervision · error · ValueError

KeyPoints detection_confidence must be given for NMS to be e

Error message

KeyPoints detection_confidence must be given for NMS to be executed.

What it means

Raised by KeyPoints.with_nms() when detection_confidence is None. NMS (non-max suppression) ranks overlapping detections by confidence and must discard low-confidence ones; without a per-skeleton detection_confidence array there is no score to sort on, so supervision refuses to run instead of silently producing arbitrary suppression.

Source

Thrown at src/supervision/key_points/core.py:1350

        Examples:
            ```python
            from supervision import _cv2 as cv2
            import supervision as sv
            from rfdetr import RFDETRKeypointPreview

            image = cv2.imread("<SOURCE_IMAGE_PATH>")
            model = RFDETRKeypointPreview()

            key_points = model.predict(image)
            key_points = key_points.with_nms(threshold=0.5)
            ```
        """
        if len(self) == 0:
            return self

        if self.detection_confidence is None:
            raise ValueError(
                "KeyPoints detection_confidence must be given for NMS to be executed."
            )

        if not class_agnostic and self.class_id is None:
            raise ValueError(
                "KeyPoints class_id must be given for NMS to be executed. If "
                "you intended to perform class agnostic NMS set "
                "class_agnostic=True."
            )

        xy = self.xy
        valid = ~np.all(xy == 0, axis=-1)
        if self.visible is not None:
            valid = valid & self.visible
        x_min = np.min(np.where(valid, xy[..., 0], np.inf), axis=1)
        y_min = np.min(np.where(valid, xy[..., 1], np.inf), axis=1)
        x_max = np.max(np.where(valid, xy[..., 0], -np.inf), axis=1)
        y_max = np.max(np.where(valid, xy[..., 1], -np.inf), axis=1)

View on GitHub (pinned to 7f254d9784)

Solutions

Pass detection_confidence when constructing the KeyPoints: sv.KeyPoints(xy=..., class_id=..., detection_confidence=scores_array).
If you only have per-keypoint confidence, derive a per-detection score (e.g. mean of keypoint_confidence) and use it as detection_confidence.
Skip NMS when no detection confidence exists — it is not applicable to single-pose or connector outputs without detection scores.

Example fix

// before
kp = sv.KeyPoints(xy=xy, class_id=class_id)
kp = kp.with_nms(threshold=0.5)  # ValueError

// after
kp = sv.KeyPoints(xy=xy, class_id=class_id, detection_confidence=scores)
kp = kp.with_nms(threshold=0.5)

Defensive patterns

Strategy: type-guard

Validate before calling

if kp.detection_confidence is None:
    raise RuntimeError("Model output lacks detection_confidence; cannot NMS")
kp = kp.with_nms(threshold=0.5)

Type guard

def can_nms(kp: sv.KeyPoints) -> bool:
    return kp.detection_confidence is not None

Try / catch

try:
    kp = kp.with_nms(threshold=0.5)
except ValueError as e:
    if "detection_confidence" in str(e):
        # derive a score or skip NMS
        pass
    else:
        raise

Prevention

Always pass detection_confidence when constructing KeyPoints that will be NMS'd.
Treat NMS as optional: guard with `if kp.detection_confidence is not None:`.
For single-pose models (one skeleton per frame) NMS is unnecessary — skip it.

When it happens

Trigger: Calling key_points.with_nms(threshold=0.5) on a KeyPoints instance constructed without the detection_confidence argument (e.g. manually built from raw xy arrays, or from a connector that does not populate it, such as from_mediapipe pose landmarks).

Common situations: Using MediaPipe pose output (which has per-landmark confidence but no whole-detection confidence) and applying NMS; or constructing KeyPoints manually from inference output and forgetting to pass detection_confidence.

Related errors

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