roboflow/supervision · error · ValueError

Invalid value type: {type(value)}. Must be an instance of {c

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.

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)

Solutions

Pass a string ('small_box' or 'large_box') or sv.OverlapFilter.SMALL_BOX / LARGE_BOX explicitly
Convert incoming config values: sv.OverlapFilter.from_value(str(value)) when the source is guaranteed textual
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)

Defensive patterns

Strategy: type-guard

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Always pass sv.OverlapFilter members or their exact string values from config
Validate config values at load time, not deep inside inference calls
Document allowed values ('small_box', 'large_box') next to your config fields

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

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