roboflow/supervision · error · ValueError

Detection area metadata must be shaped (N,) and aligned with

Error message

Detection area metadata must be shaped (N,) and aligned with detections

What it means

Raised by get_detection_size_category() when detections.data[AREA_DATA_FIELD] exists but is not a 1-D array of length N matching the number of detections. Precomputed area metadata is a fast path that skips recomputing areas from geometry, so it must align row-for-row with the Detections. A mismatch means the metadata is stale or malformed.

Source

Thrown at src/supervision/metrics/utils/object_size.py:299

    Example:
        ```pycon
        >>> import numpy as np
        >>> from supervision.config import AREA_DATA_FIELD
        >>> from supervision.detection.core import Detections
        >>> detections = Detections(
        ...     xyxy=np.array([[0, 0, 10, 10]], dtype=np.float32),
        ...     data={AREA_DATA_FIELD: np.array([2500.0])},
        ... )
        >>> get_detection_size_category(detections)
        array([2])

        ```
    """
    area_data = detections.data.get(AREA_DATA_FIELD)
    if area_data is not None:
        areas = np.asarray(area_data, dtype=np.float64)
        if len(areas.shape) != 1 or len(areas) != len(detections):
            raise ValueError(
                "Detection area metadata must be shaped (N,) and aligned "
                "with detections"
            )
        return get_area_size_category(areas)

    if metric_target == MetricTarget.BOXES:
        return get_bbox_size_category(detections.xyxy)
    if metric_target == MetricTarget.MASKS:
        mask = detections.mask
        if mask is None:
            raise ValueError("Detections mask is not available")
        return get_mask_size_category(mask)
    if metric_target == MetricTarget.ORIENTED_BOUNDING_BOXES:
        oriented_box_coordinates = detections.data.get(ORIENTED_BOX_COORDINATES)
        if oriented_box_coordinates is None:
            raise ValueError("Detections oriented bounding boxes are not available")
        return get_obb_size_category(
            cast(

View on GitHub (pinned to 7f254d9784)

Solutions

Re-align the metadata after filtering: data={AREA_DATA_FIELD: areas[keep_idx]}
Pass a 1-D array of exactly len(detections) values
Or drop the AREA_DATA_FIELD key entirely so size is recomputed from xyxy/mask/obb

Example fix

# before
areas = np.array([[100.0], [2500.0]])          # (2, 1)
dets = sv.Detections(xyxy=xyxy, data={AREA_DATA_FIELD: areas})

# after
areas = np.array([100.0, 2500.0])             # (2,)
dets = sv.Detections(xyxy=xyxy, data={AREA_DATA_FIELD: areas})

Defensive patterns

Strategy: validation

Validate before calling

from supervision.config import AREA_DATA_FIELD

areas = np.asarray(detections.data[AREA_DATA_FIELD]).reshape(-1)
assert len(areas) == len(detections), 'area metadata out of sync with detections'
detections.data[AREA_DATA_FIELD] = areas

Type guard

import numpy as np

def areas_aligned(dets: sv.Detections, areas: np.ndarray) -> bool:
    """True when areas is 1-D with one value per detection."""
    a = np.asarray(areas)
    return a.ndim == 1 and len(a) == len(dets)

Try / catch

try:
    cats = get_detection_size_category(detections, metric_target)
except ValueError as e:
    if 'aligned' in str(e):
        detections.data.pop(AREA_DATA_FIELD, None)  # recompute from geometry
        cats = get_detection_size_category(detections, metric_target)
    else:
        raise

Prevention

After filtering Detections, re-slice every entry in data dict with the same index array
Treat precomputed area metadata as derived state: regenerate it whenever detections change

When it happens

Trigger: Setting detections.data['detection_area'] (AREA_DATA_FIELD) to a scalar, an (N,1) array, or an array of a different length than len(detections) — e.g. after filtering detections with slicing, which keeps the original data array.

Common situations: Attaching areas from a previous processing stage, then filtering/subsetting detections without slicing the data dict; concatenating Detections with np.concatenate misaligned metadata; areas from a DataFrame column with extra rows.

Related errors

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