roboflow/supervision · error · ValueError

overlap_metric {overlap_metric} is not supported, only 'IOU'

Error message

overlap_metric {overlap_metric} is not supported, only 'IOU' and 'IOS' are supported

What it means

This ValueError is raised by the scalar (single-pair) box-overlap helper in supervision's IoU/NMS utilities when the `overlap_metric` argument is neither `OverlapMetric.IOU` nor `OverlapMetric.IOS`. The function computes intersection area and then picks a normalization denominator (union for IOU, smaller area for IOS); any other value has no defined normalization, so it fails fast instead of silently returning a wrong number. It is a guard against typos and against custom values injected by user code or stale versions.

Source

Thrown at src/supervision/detection/utils/iou_and_nms.py:177

    inter_w = max(0.0, _coordinate_difference(x_max_inter, x_min_inter))
    inter_h = max(0.0, _coordinate_difference(y_max_inter, y_min_inter))

    area_inter = inter_w * inter_h

    area_true = _coordinate_difference(x_max_true, x_min_true) * _coordinate_difference(
        y_max_true, y_min_true
    )
    area_det = _coordinate_difference(x_max_det, x_min_det) * _coordinate_difference(
        y_max_det, y_min_det
    )

    if overlap_metric == OverlapMetric.IOU:
        area_norm = area_true + area_det - area_inter
    elif overlap_metric == OverlapMetric.IOS:
        area_norm = min(area_true, area_det)
    else:
        raise ValueError(
            f"overlap_metric {overlap_metric} is not supported, "
            "only 'IOU' and 'IOS' are supported"
        )

    if area_norm <= 0.0:
        return 0.0

    return float(area_inter / area_norm)


def box_iou_batch(
    boxes_true: npt.NDArray[np.number],
    boxes_detection: npt.NDArray[np.number],
    overlap_metric: OverlapMetric | str = OverlapMetric.IOU,
) -> npt.NDArray[np.float32]:
    """
    Compute pairwise overlap scores between batches of bounding boxes.

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass one of the two supported values: `sv.OverlapMetric.IOU` or `sv.OverlapMetric.IOS` (or the strings 'IOU' / 'IOS', which are normalized by `OverlapMetric.from_value`).
2. If you need a different overlap metric (GIoU, DIoU, etc.), compute it yourself from `box_iou_batch` outputs or use the underlying library directly — supervision does not support it.
3. Search your code/config for the exact metric string you passed and fix the typo (e.g. 'IOU ' with trailing space, 'iou' lowercase is fine only via from_value which upper-cases).

Example fix

// before
overlap = sv.box_iou_batch(a, b, overlap_metric='GIoU')  # ValueError

// after
overlap = sv.box_iou_batch(a, b, overlap_metric=sv.OverlapMetric.IOU)

from supervision.detection.utils.iou_and_nms import OverlapMetric
assert metric in (OverlapMetric.IOU, OverlapMetric.IOS)

def is_valid_overlap_metric(v) -> bool:
    return v in (OverlapMetric.IOU, OverlapMetric.IOS)

When it happens

Trigger: Calling the internal single-pair overlap function (e.g. via `box_iou_batch`-adjacent helpers or directly) with `overlap_metric` set to a string other than 'IOU'/'IOS' (e.g. 'GIoU', 'iou_' ), a misspelled enum like `OverlapMetric.IOUU`, or a raw value that bypassed `OverlapMetric.from_value` normalization.

Common situations: Copying a metric name from another library (torchvision `complete_box_iou`, Ultralytics) that supervision does not support; upgrading supervision after enum members were renamed and an old literal still lives in config; monkeypatching or wrapping internal helpers with a custom metric.

Related errors

• Invalid value: {value}. Must be one of {cls.list()}
• `{name}` has shape {arr.shape}; expected (N, 4, 2) — each bo
• `{name}` has shape {arr.shape}; expected (N, 8) for flat YOL
• `{name}` must be 2-D (N, 8) or 3-D (N, 4, 2), got shape {arr
• Invalid asset. It should be one of the following: {valid_ass

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