roboflow/supervision · error · ValueError

class_id must be 1d np.ndarray with (n, ) shape

Error message

class_id must be 1d np.ndarray with (n, ) shape

What it means

Raised by `sv.Classifications.__post_init__` when `class_id` is not a 1-D np.ndarray of shape `(n,)`. Since `n` is derived from `len(class_id)`, the check effectively fails when `class_id` is a Python list, a 2-D array, or any other type. The library requires ndarray internally so vectorized ops (argsort, indexing in `get_top_k`) work.

Source

Thrown at src/supervision/classification/core.py:19

from __future__ import annotations

from dataclasses import dataclass
from typing import TYPE_CHECKING, Any

import numpy as np
import numpy.typing as npt

if TYPE_CHECKING:
    import torch  # type: ignore[import-not-found, unused-ignore]


def _validate_class_ids(class_id: Any, n: int) -> None:
    """
    Ensure that class_id is a 1d np.ndarray with (n, ) shape.
    """
    is_valid = isinstance(class_id, np.ndarray) and class_id.shape == (n,)
    if not is_valid:
        raise ValueError("class_id must be 1d np.ndarray with (n, ) shape")


def _validate_confidence(confidence: Any, n: int) -> None:
    """
    Ensure that confidence is a 1d np.ndarray with (n, ) shape.
    """
    if confidence is not None:
        is_valid = isinstance(confidence, np.ndarray) and confidence.shape == (n,)
        if not is_valid:
            raise ValueError("confidence must be 1d np.ndarray with (n, ) shape")


@dataclass
class Classifications:
    class_id: npt.NDArray[np.int_]
    confidence: npt.NDArray[np.floating] | None = None

    def __post_init__(self) -> None:

View on GitHub (pinned to 7f254d9784)

Solutions

1. Wrap the value: `class_id=np.asarray(class_id)` before constructing `sv.Classifications`.
2. If it is 2-D, flatten it explicitly: `np.asarray(x).reshape(-1)`.
3. Convert framework tensors first: `tensor.detach().cpu().numpy()`.

Example fix

# before
classifications = sv.Classifications(class_id=[0, 1, 2], confidence=np.array([0.3, 0.9, 0.5]))
# after
classifications = sv.Classifications(class_id=np.array([0, 1, 2]), confidence=np.array([0.3, 0.9, 0.5]))

class_id = np.asarray(class_id)
assert class_id.ndim == 1, f'class_id must be 1-D, got {class_id.shape}'

def is_valid_class_id(x: Any) -> bool:
    return isinstance(x, np.ndarray) and x.ndim == 1

When it happens

Trigger: Calling `sv.Classifications(class_id=[0, 1, 2], confidence=...)` with a plain list; passing `class_id=np.array([[0], [1]])` (2-D); passing a tensor or other array-like that is not np.ndarray.

Common situations: Coming from model wrappers that return lists of class indices; converting from a framework tensor and forgetting `.cpu().numpy()`; passing results of `np.asarray(list_of_lists)` producing 2-D.

Related errors

• confidence must be 1d np.ndarray with (n, ) shape
• Shape of np.ndarray for key '{key}' must be ({n},)
• First dimension of np.ndarray for key '{key}' must have size
• NumPy image must have at least 2 dimensions (H, W, ...). Rec
• Expected shape (H,W), (H,W,3), or (H,W,4), got {image.shape}

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