roboflow/supervision · error · ValueError

Detections mask is not available

Error message

Detections mask is not available

What it means

Raised by get_detection_size_category() when metric_target is MASKS but detections.mask is None. Size categorization for masks requires per-detection binary masks; if the Detections only carries boxes (e.g. from a detector without a segmentation head, or a connector that drops masks), the mask path cannot proceed. The code refuses rather than silently falling back to boxes.

Source

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

        ```
    """
    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(
                npt.NDArray[np.number],
                np.asarray(oriented_box_coordinates, dtype=np.float32),
            )
        )
    raise ValueError("Invalid metric type")

View on GitHub (pinned to 7f254d9784)

Solutions

1. Populate the mask: Detections(..., mask=np.stack(instance_masks))
2. Or use MetricTarget.BOXES when you only have axis-aligned boxes
3. Use a segmentation model/connector (e.g. SAM, YOLO-seg) whose output includes masks

Example fix

# before
dets = sv.Detections(xyxy=boxes)
get_detection_size_category(dets, MetricTarget.MASKS)  # mask is None

# after
dets = sv.Detections(xyxy=boxes, mask=masks)  # masks: (N, H, W) bool
get_detection_size_category(dets, MetricTarget.MASKS)

from supervision.metrics.metric_target import MetricTarget

target = MetricTarget.MASKS if detections.mask is not None else MetricTarget.BOXES
cats = get_detection_size_category(detections, target)

def has_masks(dets: sv.Detections) -> bool:
    """True when detections carry instance masks."""
    return dets.mask is not None

try:
    cats = get_detection_size_category(detections, MetricTarget.MASKS)
except ValueError as e:
    if 'mask is not available' in str(e):
        cats = get_detection_size_category(detections, MetricTarget.BOXES)
    else:
        raise

When it happens

Trigger: Calling get_detection_size_category(detections, MetricTarget.MASKS) on Detections constructed without a mask= argument, or after operations that drop the mask attribute.

Common situations: Running a mask-based metric on detector-only outputs (YOLO detection, not segmentation); Detections created from xyxy via from_* connectors that never populate mask; passing box predictions to a MASKS-target evaluation by mistake.

Related errors

• Masks must be shaped (N, H, W)
• Detections oriented bounding boxes are not available
• Invalid metric type
• Bounding boxes must be shaped (N, 4)
• Areas must be shaped (N,)

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