{"record":{"id":"2533eaeb6c0372ab","repo":"roboflow/supervision","slug":"keypoint-confidence-must-be-a-2d-np-ndarray-with-s","errorCode":null,"errorMessage":"keypoint_confidence must be a 2D np.ndarray with shape (n, m), but got shape {actual_shape}","messagePattern":"keypoint_confidence must be a 2D np\\.ndarray with shape \\(n, m\\), but got shape (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/validators/__init__.py","lineNumber":135,"sourceCode":"        )\n\n\n@deprecated(  # type: ignore[untyped-decorator]\n    target=_validate_confidence,\n    deprecated_in=\"0.29.0\",\n    remove_in=\"0.32.0\",\n)\ndef validate_confidence(confidence: Any, n: int) -> None:\n    void(confidence, n)\n\n\ndef _validate_keypoint_confidence(confidence: Any, n: int, m: int) -> None:\n    \"\"\"Validate per-keypoint confidence: 2D ``np.ndarray`` with shape ``(n, m)``.\"\"\"\n    actual_shape = str(getattr(confidence, \"shape\", None))\n\n    if confidence is not None:\n        if not isinstance(confidence, np.ndarray) or confidence.ndim != 2:\n            raise ValueError(\n                f\"keypoint_confidence must be a 2D np.ndarray with shape (n, m), but \"\n                f\"got shape {actual_shape}\"\n            )\n        if confidence.shape[0] != n:\n            raise ValueError(\n                f\"keypoint_confidence first dimension must be {n}, \"\n                f\"but got shape {actual_shape}\"\n            )\n        if n > 0 and confidence.shape[1] != m:\n            raise ValueError(\n                f\"keypoint_confidence second dimension must be {m}, but \"\n                f\"got shape {actual_shape}\"\n            )\n\n\n@deprecated(  # type: ignore[untyped-decorator]\n    target=_validate_keypoint_confidence,\n    deprecated_in=\"0.29.0\",","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/validators/__init__.py#L117-L153","documentation":"Raised by supervision.validators._validate_keypoint_confidence when the confidence passed to KeyPoints is not None and not a 2D np.ndarray. Per-keypoint confidence must be shaped (n, m): one score per keypoint for each of the n objects.","triggerScenarios":"Passing confidence as a (m,) vector for a single object, a 3D array, a Python list, or a tensor when constructing KeyPoints.","commonSituations":"Using the last axis of xy (x, y, conf) as a separate confidence without adding the object axis; models returning flat confidence vectors; forgetting .numpy() on Torch output.","solutions":["Reshape single-object confidence: confidence=scores[np.newaxis, :].","Convert tensors/lists: np.asarray(scores, dtype=np.float32) with final shape (n, m).","Leave confidence=None if you have no per-keypoint scores (use xy[..., 2] instead)."],"exampleFix":"# before\nkp = KeyPoints(xy=xy, confidence=conf)  # conf.shape == (17,) -> ValueError\n\n# after\nkp = KeyPoints(xy=xy, confidence=conf[np.newaxis, :])  # (1, 17)","handlingStrategy":"validation","validationCode":"confidence = None if confidence is None else np.asarray(confidence, dtype=np.float32)\nif confidence is not None and confidence.ndim == 1:\n    confidence = confidence[np.newaxis, :]\nkp = KeyPoints(xy=xy, confidence=confidence)","typeGuard":"def is_valid_kp_confidence(confidence: Any) -> bool:\n    return confidence is None or (\n        isinstance(confidence, np.ndarray) and confidence.ndim == 2\n    )","tryCatchPattern":null,"preventionTips":["Single object: add np.newaxis to the confidence vector.","Convert tensors to NumPy before constructing KeyPoints.","If unsure, omit confidence and encode scores in xy[..., 2]."],"tags":["keypoints","confidence","validation","shape"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}