{"record":{"id":"b9eb1abd0c625788","repo":"roboflow/supervision","slug":"coco-predictions-must-be-provided","errorCode":null,"errorMessage":"coco_predictions must be provided","messagePattern":"coco_predictions must be provided","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/metrics/mean_average_precision.py","lineNumber":703,"sourceCode":"    def __init__(\n        self,\n        coco_targets: EvaluationDataset,\n        coco_predictions: EvaluationDataset,\n        metric_target: MetricTarget = MetricTarget.BOXES,\n    ) -> None:\n        \"\"\"\n        Constructor of COCOEvaluator object.\n\n        Args:\n            coco_targets: The dataset with the ground truths.\n            coco_predictions: The dataset with the predictions.\n            metric_target: The type of detection data used to compute the IoU -\n                boxes, masks or oriented bounding boxes.\n        \"\"\"\n        if coco_targets is None:\n            raise ValueError(\"coco_targets must be provided\")\n        if coco_predictions is None:\n            raise ValueError(\"coco_predictions must be provided\")\n\n        self.coco_targets = coco_targets\n        self.coco_predictions = coco_predictions\n        self.metric_target = metric_target\n        # List of dictionaries containing the evaluation results\n        # len(eval_imgs) = (categories) * (area_ranges) * (images)\n        # For COCO 2017: len(eval_images) = 80 * 4 * 5000 = 1600000\n        self.eval_imgs: list[_TypeEvaluationImageResult | None] = []\n        # Dictionary of accumulated results\n        self.results: dict[str, object] = {}\n        # Dictionary of targets for evaluation\n        self._targets: defaultdict[tuple[int, int], list[_TypeCocoDict]] = defaultdict(\n            list\n        )\n        self._predictions: defaultdict[tuple[int, int], list[_TypeCocoDict]] = (\n            defaultdict(list)\n        )\n        # Parameters for evaluation","sourceCodeStart":685,"sourceCodeEnd":721,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/metrics/mean_average_precision.py#L685-L721","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Validate the predictions dataset before constructing: fail with a descriptive error naming the file/model run","Regenerate or correctly locate the predictions artifacts","Use the public MeanAveragePrecision API, which manages dataset construction end-to-end","Avoid try/except that swallows load errors into None returns"],"exampleFix":"# before\ncoco_det = maybe_load(preds_path)   # None when file missing\nevaluator = COCOEvaluator(coco_gt, coco_det)\n\n# after\ncoco_det = maybe_load(preds_path)\nif coco_det is None:\n    raise FileNotFoundError(f'predictions not found at {preds_path}')\nevaluator = COCOEvaluator(coco_gt, coco_det)","handlingStrategy":"validation","validationCode":"if coco_predictions is None:\n    raise ValueError(f'predictions missing — expected output at {pred_path!r}')\nevaluator = COCOEvaluator(coco_targets, coco_predictions)","typeGuard":null,"tryCatchPattern":"try:\n    COCOEvaluator(gt, det)\nexcept ValueError as e:\n    if 'coco_predictions' in str(e):\n        raise RuntimeError('prediction dataset missing — run inference first') from e\n    raise","preventionTips":["Ensure inference artifacts exist before evaluation starts","Never swallow load errors into None","Use public update()/compute() instead of internal COCOEvaluator"],"tags":["metrics","mean-average-precision","coco","null-check","constructor-validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}