roboflow/supervision · error · ValueError

Invalid value: {value}. Must be one of {cls.list()}

Error message

Invalid value: {value}. Must be one of {cls.list()}

What it means

`OverlapFilter.from_value` converts a user-supplied string into the `OverlapFilter` enum, which only accepts 'none', 'non_max_suppression', or 'non_max_merge' (case-insensitive). This error is raised when the lower-cased string matches no member — e.g. 'nms', 'non-max-suppression' (hyphens), or 'NON_MAX_MERGE '. The enum selects how overlapping detections are post-processed by `Detections.with_nms` and friends.

Source

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

    NONE = "none"
    NON_MAX_SUPPRESSION = "non_max_suppression"
    NON_MAX_MERGE = "non_max_merge"

    @classmethod
    def list(cls) -> list[str]:
        return list(map(lambda member: member.value, cls))

    @classmethod
    def from_value(cls, value: OverlapFilter | str) -> OverlapFilter:
        if isinstance(value, cls):
            return value
        if isinstance(value, str):
            value = value.lower()
            try:
                return cls(value)
            except ValueError:
                raise ValueError(f"Invalid value: {value}. Must be one of {cls.list()}")
        raise ValueError(
            f"Invalid value type: {type(value)}. Must be an instance of "
            f"{cls.__name__} or str."
        )


class OverlapMetric(Enum):
    """
    Enum specifying the metric for measuring overlap between detections.

    Attributes:
        IOU: Intersection over Union. A region-overlap metric that compares
            two shapes (usually bounding boxes or masks) by normalising the
            shared area with the area of their union.
        IOS: Intersection over Smaller, a region-overlap metric that compares
            two shapes (usually bounding boxes or masks) by normalising the
            shared area with the smaller of the two shapes.
    """

View on GitHub (pinned to 7f254d9784)

Solutions

1. Use one of the exact values: 'none', 'non_max_suppression', 'non_max_merge' (any case), or the enum members `sv.OverlapFilter.NON_MAX_SUPPRESSION` / `NON_MAX_MERGE` / `NONE`.
2. Map user-facing shorthand to enum values at your CLI boundary: `{'nms': 'non_max_suppression', 'nmm': 'non_max_merge'}`.
3. Echo valid options to the user on failure: `sv.OverlapFilter.list()`.

Example fix

# before
dets = dets.with_nms(0.5, overlap_filter='nms')  # ValueError

# after
dets = dets.with_nms(0.5, overlap_filter=sv.OverlapFilter.NON_MAX_SUPPRESSION)

ALIASES = {'nms': 'non_max_suppression', 'nmm': 'non_max_merge', 'none': 'none'}
overlap_filter = sv.OverlapFilter.from_value(ALIASES.get(raw.strip().lower(), raw.strip()))

def is_overlap_filter_value(v) -> bool:
    try:
        OverlapFilter.from_value(v)
        return True
    except ValueError:
        return False

When it happens

Trigger: Calling `detections.with_nms(threshold, overlap_filter='nms')` — the common abbreviation is not accepted; or passing 'non-max-merge' with hyphens from a CLI argument or config file.

Common situations: CLI flags and YAML configs using abbreviations ('nms', 'suppress') or hyphenated spellings; users assuming enum values mirror another library's naming.

Related errors

• overlap_metric {overlap_metric} is not supported, only 'IOU'
• Invalid value type: {type(value)}. Must be an instance of {c
• Empty group detected when non-max-merging detections: {merge
• `{name}` has shape {arr.shape}; expected (N, 5) or (N, 6).
• KeyPoints detection_confidence must be given for NMS to be e

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