roboflow/supervision · error · ValueError

keypoint_confidence must be a 2D np.ndarray with shape (n, m

Error message

keypoint_confidence must be a 2D np.ndarray with shape (n, m), but got shape {actual_shape}

What it means

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.

Source

Thrown at src/supervision/validators/__init__.py:135

        )


@deprecated(  # type: ignore[untyped-decorator]
    target=_validate_confidence,
    deprecated_in="0.29.0",
    remove_in="0.32.0",
)
def validate_confidence(confidence: Any, n: int) -> None:
    void(confidence, n)


def _validate_keypoint_confidence(confidence: Any, n: int, m: int) -> None:
    """Validate per-keypoint confidence: 2D ``np.ndarray`` with shape ``(n, m)``."""
    actual_shape = str(getattr(confidence, "shape", None))

    if confidence is not None:
        if not isinstance(confidence, np.ndarray) or confidence.ndim != 2:
            raise ValueError(
                f"keypoint_confidence must be a 2D np.ndarray with shape (n, m), but "
                f"got shape {actual_shape}"
            )
        if confidence.shape[0] != n:
            raise ValueError(
                f"keypoint_confidence first dimension must be {n}, "
                f"but got shape {actual_shape}"
            )
        if n > 0 and confidence.shape[1] != m:
            raise ValueError(
                f"keypoint_confidence second dimension must be {m}, but "
                f"got shape {actual_shape}"
            )


@deprecated(  # type: ignore[untyped-decorator]
    target=_validate_keypoint_confidence,
    deprecated_in="0.29.0",

View on GitHub (pinned to 7f254d9784)

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

Example fix

# before
kp = KeyPoints(xy=xy, confidence=conf)  # conf.shape == (17,) -> ValueError

# after
kp = KeyPoints(xy=xy, confidence=conf[np.newaxis, :])  # (1, 17)

Defensive patterns

Strategy: validation

Validate before calling

confidence = None if confidence is None else np.asarray(confidence, dtype=np.float32)
if confidence is not None and confidence.ndim == 1:
    confidence = confidence[np.newaxis, :]
kp = KeyPoints(xy=xy, confidence=confidence)

Type guard

def is_valid_kp_confidence(confidence: Any) -> bool:
    return confidence is None or (
        isinstance(confidence, np.ndarray) and confidence.ndim == 2
    )

Prevention

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].

When it happens

Trigger: Passing confidence as a (m,) vector for a single object, a 3D array, a Python list, or a tensor when constructing KeyPoints.

Common situations: 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.

Related errors

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