roboflow/supervision · error · ValueError

class_id must be a 1D np.ndarray with shape {expected_shape}

Error message

class_id must be a 1D np.ndarray with shape {expected_shape}, but got shape {actual_shape}

What it means

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.

Source

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


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


def _validate_class_id(class_id: Any, n: int) -> None:
    expected_shape = f"({n},)"
    actual_shape = str(getattr(class_id, "shape", None))
    is_valid = class_id is None or (
        isinstance(class_id, np.ndarray) and class_id.shape == (n,)
    )
    if not is_valid:
        raise ValueError(
            f"class_id must be a 1D np.ndarray with shape {expected_shape}, but got "
            f"shape {actual_shape}"
        )


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


def _validate_confidence(confidence: Any, n: int) -> None:
    """Validate detection-level confidence: 1D ``np.ndarray`` with shape ``(n,)``."""
    expected_shape = f"({n},)"
    actual_shape = str(getattr(confidence, "shape", None))

View on GitHub (pinned to 7f254d9784)

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.

Example fix

# before
dets = Detections(xyxy=boxes, class_id=[0, 1])  # list -> ValueError

# after
dets = Detections(xyxy=boxes, class_id=np.array([0, 1]))

Defensive patterns

Strategy: type-guard

Validate before calling

n = len(xyxy)
class_id = None if class_id is None else np.asarray(class_id).reshape(n)
dets = Detections(xyxy=xyxy, class_id=class_id)

Type guard

def is_valid_class_id(class_id: Any, n: int) -> bool:
    return class_id is None or (
        isinstance(class_id, np.ndarray) and class_id.shape == (n,)
    )

Prevention

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.

When it happens

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

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

Related errors

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