{"record":{"id":"4cfdfb19c4e26192","repo":"roboflow/supervision","slug":"invalid-value-type-type-value-must-be-an-inst-4cfdfb","errorCode":null,"errorMessage":"Invalid value type: {type(value)}. Must be an instance of {cls.__name__} or str.","messagePattern":"Invalid value type: (.+?)\\. Must be an instance of (.+?) or str\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/utils/iou_and_nms.py","lineNumber":49,"sourceCode":"    NONE = \"none\"\n    NON_MAX_SUPPRESSION = \"non_max_suppression\"\n    NON_MAX_MERGE = \"non_max_merge\"\n\n    @classmethod\n    def list(cls) -> list[str]:\n        return list(map(lambda member: member.value, cls))\n\n    @classmethod\n    def from_value(cls, value: OverlapFilter | str) -> OverlapFilter:\n        if isinstance(value, cls):\n            return value\n        if isinstance(value, str):\n            value = value.lower()\n            try:\n                return cls(value)\n            except ValueError:\n                raise ValueError(f\"Invalid value: {value}. Must be one of {cls.list()}\")\n        raise ValueError(\n            f\"Invalid value type: {type(value)}. Must be an instance of \"\n            f\"{cls.__name__} or str.\"\n        )\n\n\nclass OverlapMetric(Enum):\n    \"\"\"\n    Enum specifying the metric for measuring overlap between detections.\n\n    Attributes:\n        IOU: Intersection over Union. A region-overlap metric that compares\n            two shapes (usually bounding boxes or masks) by normalising the\n            shared area with the area of their union.\n        IOS: Intersection over Smaller, a region-overlap metric that compares\n            two shapes (usually bounding boxes or masks) by normalising the\n            shared area with the smaller of the two shapes.\n    \"\"\"\n","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/utils/iou_and_nms.py#L31-L67","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","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"],"exampleFix":"# before\nkeep = sv.box_non_max_suppression(predictions, iou_threshold=0.5, overlap_filter=None)\n# after\nkeep = sv.box_non_max_suppression(predictions, iou_threshold=0.5, overlap_filter=sv.OverlapFilter.SMALL_BOX)","handlingStrategy":"type-guard","validationCode":"import supervision as sv\n\ndef coerce_overlap_filter(value):\n    if value is None:\n        return sv.OverlapFilter.SMALL_BOX\n    return sv.OverlapFilter.from_value(value if isinstance(value, str) else str(value))","typeGuard":"def is_overlap_filter_like(v) -> bool:\n    import supervision as sv\n    return isinstance(v, (sv.OverlapFilter, str))","tryCatchPattern":"try:\n    filt = sv.OverlapFilter.from_value(cfg['overlap_filter'])\nexcept ValueError as e:\n    if \"Invalid value type\" in str(e):\n        filt = sv.OverlapFilter.SMALL_BOX  # explicit fallback default\n    else:\n        raise","preventionTips":["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"],"tags":["enum","validation","nms","api-misuse"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}