roboflow/supervision · error · ValueError

Detections confidence must be given for Soft-NMS to be execu

Error message

Detections confidence must be given for Soft-NMS to be executed.

What it means

Detections.with_soft_non_max_suppression (with_soft_nms) decays confidence values of overlapping boxes using a Gaussian; the algorithm is undefined without scores. When self.confidence is None it raises this ValueError before any dispatch.

Source

Thrown at src/supervision/detection/core.py:3118

                (like `with_nms`). If `None` (default), all detections are
                kept, with their confidence rescaled in place on the returned
                copy.

        Returns:
            A new Detections object with decayed confidence scores and,
                if `score_threshold` is given, filtered to a real subset.
                The original `Detections` instance is never modified.

        Raises:
            ValueError: If `confidence` is None.
                If `class_id` is None and class_agnostic is False.
                If `sigma` is not greater than `0`.
        """
        if len(self) == 0:
            return self

        if self.confidence is None:
            raise ValueError(
                "Detections confidence must be given for Soft-NMS to be executed."
            )

        predictions = self._build_nms_predictions(class_agnostic, "Soft-NMS")

        if self.mask is not None:
            decayed_confidence = mask_soft_non_max_suppression(
                predictions=predictions,
                masks=self.mask,
                sigma=sigma,
            )
        else:
            decayed_confidence = box_soft_non_max_suppression(
                predictions=predictions,
                sigma=sigma,
            )

        result = self.select(np.arange(len(self)))

View on GitHub (pinned to 7f254d9784)

Solutions

1. Attach real scores if available: cls(xyxy=..., confidence=scores).
2. Attach uniform dummy confidence (np.ones(len(detections))) only when you accept IoU-only soft suppression semantics.
3. Skip soft-NMS for score-less sources and deduplicate by geometry/text instead.

Example fix

# before
detections = sv.Detections(xyxy=boxes)  # no confidence
out = detections.with_soft_nms(sigma=0.5)

# after
detections = sv.Detections(xyxy=boxes, confidence=np.ones(len(boxes)))
out = detections.with_soft_nms(sigma=0.5)

if detections.confidence is None:
    detections = sv.Detections(
        xyxy=detections.xyxy,
        class_id=detections.class_id,
        confidence=np.ones(len(detections), dtype=float),
    )
out = detections.with_soft_nms(sigma=0.5)

def soft_nms_ready(dets: sv.Detections) -> bool:
    return dets.confidence is not None and (dets.class_id is not None or True)

try:
    out = detections.with_soft_nms(sigma=0.5)
except ValueError as e:
    if 'confidence must be given' in str(e):
        out = detections  # no scores -> nothing to decay
    else:
        raise

When it happens

Trigger: Calling detections.with_soft_nms(sigma=..., ...) on a Detections lacking confidence — SAM/segmentation outputs, VLM connectors that return only class names, or manual construction without the confidence argument.

Common situations: Same family as NMS/NMM: score-less connectors (from_sam, from_paligemma-style outputs), hand-assembled boxes, or pipelines where confidence was stripped by an earlier with_nmsless transform or custom slicing that dropped fields.

Related errors

• Detections confidence must be given for NMS to be executed.
• Detections confidence must be given for NMM to be executed.
• No edges defined for class_id={class_id}.
• KeyPoints detection_confidence must be given for NMS to be e
• Detections must have class_id attribute.

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