roboflow/supervision · error · ValueError

coco_targets must be provided

Error message

coco_targets must be provided

What it means

COCOEvaluator, the COCO-backend evaluator inside MeanAveragePrecision, requires both a ground-truth and a predictions dataset. This ValueError fires from its constructor when coco_targets is None. The parameters have no default that makes sense, so the guard turns an accidental None (e.g. a variable that failed to load) into an explicit failure instead of an AttributeError deep inside evaluation.

Source

Thrown at src/supervision/metrics/mean_average_precision.py:701

    """

    def __init__(
        self,
        coco_targets: EvaluationDataset,
        coco_predictions: EvaluationDataset,
        metric_target: MetricTarget = MetricTarget.BOXES,
    ) -> None:
        """
        Constructor of COCOEvaluator object.

        Args:
            coco_targets: The dataset with the ground truths.
            coco_predictions: The dataset with the predictions.
            metric_target: The type of detection data used to compute the IoU -
                boxes, masks or oriented bounding boxes.
        """
        if coco_targets is None:
            raise ValueError("coco_targets must be provided")
        if coco_predictions is None:
            raise ValueError("coco_predictions must be provided")

        self.coco_targets = coco_targets
        self.coco_predictions = coco_predictions
        self.metric_target = metric_target
        # List of dictionaries containing the evaluation results
        # len(eval_imgs) = (categories) * (area_ranges) * (images)
        # For COCO 2017: len(eval_images) = 80 * 4 * 5000 = 1600000
        self.eval_imgs: list[_TypeEvaluationImageResult | None] = []
        # Dictionary of accumulated results
        self.results: dict[str, object] = {}
        # Dictionary of targets for evaluation
        self._targets: defaultdict[tuple[int, int], list[_TypeCocoDict]] = defaultdict(
            list
        )
        self._predictions: defaultdict[tuple[int, int], list[_TypeCocoDict]] = (
            defaultdict(list)

View on GitHub (pinned to 7f254d9784)

Solutions

  1. Check the loader result: if coco_targets is None: raise with your file path/context before constructing
  2. Fix the underlying load (path, JSON validity, schema) so a real EvaluationDataset is produced
  3. Prefer the public API: mAP via MeanAveragePrecision().update(preds, targets).compute() which builds datasets internally
  4. Add defensive asserts at pipeline boundaries where datasets enter

Example fix

# before
coco_gt = try_load(gt_path)          # returns None on failure
 evaluator = COCOEvaluator(coco_gt, coco_det)   # boom

# after
coco_gt = try_load(gt_path)
if coco_gt is None:
    raise FileNotFoundError(f'could not load ground truth from {gt_path}')
evaluator = COCOEvaluator(coco_gt, coco_det)
Defensive patterns

Strategy: validation

Validate before calling

if coco_targets is None:
    raise ValueError(f'ground truth failed to load from {gt_path!r}')
evaluator = COCOEvaluator(coco_targets, coco_predictions)

Try / catch

try:
    COCOEvaluator(gt, det)
except ValueError as e:
    if 'coco_targets' in str(e):
        raise RuntimeError('ground-truth dataset missing — check loader/paths') from e
    raise

Prevention

When it happens

Trigger: COCOEvaluator(None, coco_det) because the ground-truth JSON failed to parse or the file path was wrong so the loader returned None; a function that conditionally loads targets (try/except returning None) and passes the result unchecked; direct instantiation of COCOEvaluator by user code (it is internal to the mAP pipeline).

Common situations: Silent-failure loaders (json.load wrapped in except: return None); wrong file paths in config; empty argument after refactoring; users reaching for the internal COCO API instead of MeanAveragePrecision.update().

Related errors

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