roboflow/supervision · error · ValueError

keypoint_confidence first dimension must be {n}, but got sha

Error message

keypoint_confidence first dimension must be {n}, but got shape {actual_shape}

What it means

Raised by supervision.validators._validate_keypoint_confidence when confidence is 2D but its first dimension differs from n, the number of key-point objects in xy. Each object needs its own row of m per-keypoint scores.

Source

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

    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",
    remove_in="0.32.0",
)
def validate_key_point_confidence(confidence: Any, n: int, m: int) -> None:
    void(confidence, n, m)

View on GitHub (pinned to 7f254d9784)

Solutions

Index confidence with the same object mask used on xy: conf = conf[keep_idx].
Tile a shared row only if truly identical: np.tile(conf, (n, 1)).
Verify conf.shape == (xy.shape[0], xy.shape[1]) with an assert before construction.

Example fix

# before
kp = KeyPoints(xy=xy, confidence=conf)  # xy:(4,17,2), conf:(1,17)

# after
kp = KeyPoints(xy=xy, confidence=conf[keep_idx])  # keep_idx also applied to xy

Defensive patterns

Strategy: validation

Validate before calling

confidence = np.asarray(confidence, dtype=np.float32)
assert confidence.shape[0] == xy.shape[0], "one confidence row per object"
kp = KeyPoints(xy=xy, confidence=confidence)

Type guard

def kp_conf_rows_match(confidence: np.ndarray, xy: np.ndarray) -> bool:
    return confidence.ndim == 2 and confidence.shape[0] == xy.shape[0]

Prevention

Index confidence with the same object mask as xy.
Assert shape (n, m) matches xy before construction.
Never reuse one object's confidence for a multi-object batch.

When it happens

Trigger: Constructing KeyPoints with xy of shape (4, 17, 2) but confidence of shape (1, 17) or (3, 17).

Common situations: Detecting multiple people but reusing a single skeleton's confidence; filtering detected objects without filtering confidence rows; model returning per-frame rather than per-object scores.

Related errors

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