{"record":{"id":"cc3bb072f3cb8b85","repo":"roboflow/supervision","slug":"class-id-must-be-a-1d-np-ndarray-with-shape-expec","errorCode":null,"errorMessage":"class_id must be a 1D np.ndarray with shape {expected_shape}, but got shape {actual_shape}","messagePattern":"class_id must be a 1D np\\.ndarray with shape (.+?), but got shape (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/validators/__init__.py","lineNumber":91,"sourceCode":"\n\n@deprecated(  # type: ignore[untyped-decorator]\n    target=_validate_mask,\n    deprecated_in=\"0.29.0\",\n    remove_in=\"0.32.0\",\n)\ndef validate_mask(mask: Any, n: int) -> None:\n    void(mask, n)\n\n\ndef _validate_class_id(class_id: Any, n: int) -> None:\n    expected_shape = f\"({n},)\"\n    actual_shape = str(getattr(class_id, \"shape\", None))\n    is_valid = class_id is None or (\n        isinstance(class_id, np.ndarray) and class_id.shape == (n,)\n    )\n    if not is_valid:\n        raise ValueError(\n            f\"class_id must be a 1D np.ndarray with shape {expected_shape}, but got \"\n            f\"shape {actual_shape}\"\n        )\n\n\n@deprecated(  # type: ignore[untyped-decorator]\n    target=_validate_class_id,\n    deprecated_in=\"0.29.0\",\n    remove_in=\"0.32.0\",\n)\ndef validate_class_id(class_id: Any, n: int) -> None:\n    void(class_id, n)\n\n\ndef _validate_confidence(confidence: Any, n: int) -> None:\n    \"\"\"Validate detection-level confidence: 1D ``np.ndarray`` with shape ``(n,)``.\"\"\"\n    expected_shape = f\"({n},)\"\n    actual_shape = str(getattr(confidence, \"shape\", None))","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/validators/__init__.py#L73-L109","documentation":"Raised by supervision.validators._validate_class_id when class_id is provided to Detections but is not None and not a 1D np.ndarray of shape (n,), where n is the number of rows in xyxy. class_id assigns each detection its class index.","triggerScenarios":"Passing class_id=[0, 1, 2] (a Python list) to Detections; passing a (n, 1) column vector; passing an array whose length differs from len(xyxy).","commonSituations":"Using class names instead of integer indices; forgetting np.array() around a list; deriving class_id from model.names dict values; reshaping class ids into 2D during preprocessing.","solutions":["Convert to a 1D array of matching length: class_id=np.array([0, 1, 2]).","Ensure len(class_id) == len(xyxy); broadcast a single class with np.full(len(xyxy), cls).","Use .ravel() on a column vector: class_id=ids.ravel().","Leave class_id=None when you have no class information."],"exampleFix":"# before\ndets = Detections(xyxy=boxes, class_id=[0, 1])  # list -> ValueError\n\n# after\ndets = Detections(xyxy=boxes, class_id=np.array([0, 1]))","handlingStrategy":"type-guard","validationCode":"n = len(xyxy)\nclass_id = None if class_id is None else np.asarray(class_id).reshape(n)\ndets = Detections(xyxy=xyxy, class_id=class_id)","typeGuard":"def is_valid_class_id(class_id: Any, n: int) -> bool:\n    return class_id is None or (\n        isinstance(class_id, np.ndarray) and class_id.shape == (n,)\n    )","tryCatchPattern":null,"preventionTips":["Always wrap class ids with np.asarray(...).ravel().","Use np.full(len(detections), cls) to broadcast one class.","Apply the same boolean filter to class_id as to xyxy."],"tags":["detections","validation","shape","numpy"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}