roboflow/supervision · error · ValueError

Invalid value: . Must be one of

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.

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 is not supported, only 'IOU' and 'IOS' are…
• Empty group detected when non-max-merging detections
• Invalid value type: . Must be an instance of or str.
• ` ` has shape ; expected (N, 5) or (N, 6).
• is not supported.

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

Appendix: 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)