roboflow/supervision · error · ValueError

coco_predictions must be provided

Error message

coco_predictions must be provided

What it means

COCOEvaluator's constructor raises this ValueError when coco_predictions is None. Like its sibling check for targets, it enforces that both the ground-truth and prediction datasets are present before evaluation state is initialized. Users normally never instantiate COCOEvaluator directly — MeanAveragePrecision.compute() does — so hitting it means direct internal API use with a failed predictions load.

Source

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

    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)
        )
        # Parameters for evaluation

View on GitHub (pinned to 7f254d9784)

Solutions

  1. Validate the predictions dataset before constructing: fail with a descriptive error naming the file/model run
  2. Regenerate or correctly locate the predictions artifacts
  3. Use the public MeanAveragePrecision API, which manages dataset construction end-to-end
  4. Avoid try/except that swallows load errors into None returns

Example fix

# before
coco_det = maybe_load(preds_path)   # None when file missing
evaluator = COCOEvaluator(coco_gt, coco_det)

# after
coco_det = maybe_load(preds_path)
if coco_det is None:
    raise FileNotFoundError(f'predictions not found at {preds_path}')
evaluator = COCOEvaluator(coco_gt, coco_det)
Defensive patterns

Strategy: validation

Validate before calling

if coco_predictions is None:
    raise ValueError(f'predictions missing — expected output at {pred_path!r}')
evaluator = COCOEvaluator(coco_targets, coco_predictions)

Try / catch

try:
    COCOEvaluator(gt, det)
except ValueError as e:
    if 'coco_predictions' in str(e):
        raise RuntimeError('prediction dataset missing — run inference first') from e
    raise

Prevention

When it happens

Trigger: COCOEvaluator(coco_gt, None) after a predictions JSON load failed or a path was wrong; passing an unset variable; calling load_predictions output without checking it exists; using the internal COCO backend directly in a custom evaluation script.

Common situations: Model produced no output file yet (empty predictions path) and the loader returned None; race conditions reading results written by another process; refactor left a variable uninitialized; silent except blocks swallowing load errors.

Related errors

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