{"record":{"id":"5700ac7bba7f7f6f","repo":"roboflow/supervision","slug":"value-for-key-key-must-be-a-list-or-np-ndarray","errorCode":null,"errorMessage":"Value for key '{key}' must be a list or np.ndarray","messagePattern":"Value for key '(.+?)' must be a list or np\\.ndarray","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/validators/__init__.py","lineNumber":204,"sourceCode":")\ndef validate_tracker_id(tracker_id: Any, n: int) -> None:\n    void(tracker_id, n)\n\n\ndef _validate_data(data: dict[str, Any], n: int) -> None:\n    for key, value in data.items():\n        if isinstance(value, list):\n            if len(value) != n:\n                raise ValueError(f\"Length of list for key '{key}' must be {n}\")\n        elif isinstance(value, np.ndarray):\n            if value.ndim == 1 and value.shape[0] != n:\n                raise ValueError(f\"Shape of np.ndarray for key '{key}' must be ({n},)\")\n            elif value.ndim > 1 and value.shape[0] != n:\n                raise ValueError(\n                    f\"First dimension of np.ndarray for key '{key}' must have size {n}\"\n                )\n        else:\n            raise ValueError(f\"Value for key '{key}' must be a list or np.ndarray\")\n\n\n@deprecated(  # type: ignore[untyped-decorator]\n    target=_validate_data,\n    deprecated_in=\"0.29.0\",\n    remove_in=\"0.32.0\",\n)\ndef validate_data(data: dict[str, Any], n: int) -> None:\n    void(data, n)\n\n\ndef _validate_xy(xy: Any, n: int, m: int) -> None:\n    expected_shape = f\"({n}, {m}, 2) or ({n}, {m}, 3)\"\n    actual_shape = str(getattr(xy, \"shape\", None))\n\n    if not isinstance(xy, np.ndarray) or xy.ndim != 3 or xy.shape[2] not in (2, 3):\n        raise ValueError(\n            f\"xy must be a 3D np.ndarray with shape {expected_shape}, but got shape \"","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/validators/__init__.py#L186-L222","documentation":"Raised by supervision.validators._validate_data when a value in the Detections.data dict is neither a list nor an np.ndarray. data entries are per-detection columns; scalars, dicts, strings-as-scalar, or tensors are rejected because they cannot be aligned with xyxy.","triggerScenarios":"Passing data={\"score\": 0.9} (a bare float), data={\"meta\": {\"frame\": 1}} (a dict), or a Torch tensor as a data value when constructing Detections.","commonSituations":"Trying to attach global/frame-level metadata to Detections (data is per-detection only); passing model tensors without .cpu().numpy(); storing a single class name string instead of a per-detection list.","solutions":["Broadcast scalars: data={\"score\": np.full(n, 0.9)}.","Convert tensors: tensor.detach().cpu().numpy().","Keep frame-level metadata outside Detections (e.g. pass alongside in your own struct); data is per-detection only.","Use recognized keys from supervision.config (e.g. CLASS_NAME_DATA_FIELD) with per-detection arrays."],"exampleFix":"# before\ndets = Detections(xyxy=boxes, data={\"frame_idx\": 42})  # scalar -> ValueError\n\n# after\nframe_idx = 42  # keep frame-level info outside Detections\ndets = Detections(xyxy=boxes, data={\"conf\": np.full(len(boxes), 0.9)})","handlingStrategy":"validation","validationCode":"n = len(xyxy)\ndata = {\n    k: (v if isinstance(v, (list, np.ndarray)) else np.full(n, v))\n    for k, v in data.items()\n}\ndets = Detections(xyxy=xyxy, data=data)","typeGuard":"def data_values_are_columns(data: dict[str, Any]) -> bool:\n    return all(isinstance(v, (list, np.ndarray)) for v in data.values())","tryCatchPattern":null,"preventionTips":["Remember Detections.data is per-detection columns only.","Keep frame-level metadata outside the Detections object.","Convert tensors to np.ndarray before storing them in data."],"tags":["detections","data-dict","validation","type"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}