roboflow/supervision · error · ValueError

Invalid value type: . Must be an instance of or str.

Error message

Invalid value type: {type(value)}. Must be an instance of {cls.__name__} or str.

What it means

Raised by OverlapFilter.from_value when the value passed as overlap_filter is neither an OverlapFilter enum member, nor a str, nor convertible to one — e.g. an int, None, or an arbitrary object. from_value is the coercion gate for every public API parameter typed OverlapFilter | str, so a wrong-typed argument surfaces here with an explicit message.

Solutions

1. Pass a string ('small_box' or 'large_box') or sv.OverlapFilter.SMALL_BOX / LARGE_BOX explicitly
2. Convert incoming config values: sv.OverlapFilter.from_value(str(value)) when the source is guaranteed textual
3. Validate/normalize the parameter at your config layer before it reaches the supervision API

Example fix

# before
keep = sv.box_non_max_suppression(predictions, iou_threshold=0.5, overlap_filter=None)
# after
keep = sv.box_non_max_suppression(predictions, iou_threshold=0.5, overlap_filter=sv.OverlapFilter.SMALL_BOX)

import supervision as sv

def coerce_overlap_filter(value):
    if value is None:
        return sv.OverlapFilter.SMALL_BOX
    return sv.OverlapFilter.from_value(value if isinstance(value, str) else str(value))

def is_overlap_filter_like(v) -> bool:
    import supervision as sv
    return isinstance(v, (sv.OverlapFilter, str))

try:
    filt = sv.OverlapFilter.from_value(cfg['overlap_filter'])
except ValueError as e:
    if "Invalid value type" in str(e):
        filt = sv.OverlapFilter.SMALL_BOX  # explicit fallback default
    else:
        raise

When it happens

Trigger: Passing overlap_filter=None, overlap_filter=0, or overlap_filter=['small_box'] to APIs such as box_nms/box_non_max_suppression-family functions or Detections.with_nms; from_value only accepts OverlapFilter instances or strings like 'small_box'/'large_box'.

Common situations: Plumbing a config value (int/None from YAML or CLI) directly into overlap_filter; passing an Enum from a different library with matching member names; version upgrade where the parameter changed from str-only to enum-or-str and old typed values were kept.

Related errors

• Invalid metric target
• Invalid metric target
• Invalid metric type
• Invalid value: . Must be one of
• Invalid vlm value: . Must be one of

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

Appendix: source

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

    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)