{"record":{"id":"3d426656ccd09788","repo":"roboflow/supervision","slug":"could-not-put-detections-into-trace-because-detect","errorCode":null,"errorMessage":"Could not put detections into Trace because Detections do not have tracker_id.","messagePattern":"Could not put detections into Trace because Detections do not have tracker_id\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/annotators/utils.py","lineNumber":378,"sourceCode":"class Trace:\n    def __init__(\n        self,\n        max_size: int | None = None,\n        start_frame_id: int = 0,\n        anchor: Position = Position.CENTER,\n    ) -> None:\n        self.current_frame_id = start_frame_id\n        self.max_size = max_size\n        self.anchor = anchor\n\n        self.frame_id: npt.NDArray[np.int_] = np.array([], dtype=int)\n        self.xy: npt.NDArray[np.float32] = np.empty((0, 2), dtype=np.float32)\n        self.tracker_id: npt.NDArray[np.int_] = np.array([], dtype=int)\n\n    def put(self, detections: Detections) -> None:\n        \"\"\"Append a frame of detections to the trace history.\"\"\"\n        if detections.tracker_id is None:\n            raise ValueError(\n                \"Could not put detections into Trace because \"\n                \"Detections do not have tracker_id.\"\n            )\n\n        frame_id: npt.NDArray[np.int_] = np.full(\n            len(detections), self.current_frame_id, dtype=int\n        )\n        self.frame_id = np.concatenate([self.frame_id, frame_id])\n        self.xy = np.concatenate(\n            [\n                self.xy,\n                detections.get_anchors_coordinates(self.anchor),\n            ]\n        )\n        self.tracker_id = np.concatenate([self.tracker_id, detections.tracker_id])\n\n        unique_frame_id = np.unique(self.frame_id)\n","sourceCodeStart":360,"sourceCodeEnd":396,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/annotators/utils.py#L360-L396","documentation":"Raised by `Trace.put(detections)` (the history buffer behind `TraceAnnotator`) when the incoming `Detections` lack `tracker_id`. A trace is a per-object trajectory keyed by tracker id, so detections without tracking ids cannot be attributed to any trace.","triggerScenarios":"Calling `trace_annotator.annotate(scene, detections)` or `trace.put(detections)` on raw model detections that never passed through a tracker; calling `ByteTrack().update_with_detections(...)` but discarding its result and annotating the pre-track detections; annotating every Nth frame after a pipeline refactor dropped the tracker step.","commonSituations":"Running detection-only models (no tracker in the pipeline) then adding TraceAnnotator; testing annotators on synthetic `Detections(...)` fixtures built without `tracker_id`; branching code where the tracker is only invoked when a flag is set but TraceAnnotator always runs.","solutions":["Add a tracker step: `detections = sv.ByteTrack().update_with_detections(detections)` before `TraceAnnotator.annotate`.","If you only need per-frame annotation (no trajectory), use `BoxAnnotator`/`LabelAnnotator` instead of `TraceAnnotator`.","When building synthetic test detections, include `tracker_id=np.array([...])`."],"exampleFix":"# before\nannotator = sv.TraceAnnotator()\nannotator.annotate(frame.copy(), detections)  # raw detections, no tracker_id\n\n# after\ntracker = sv.ByteTrack()\ndetections = tracker.update_with_detections(detections)\nannotator.annotate(frame.copy(), detections)","handlingStrategy":"type-guard","validationCode":"from supervision.annotators.utils import PENDING_TRACK_ID\n\nif detections.tracker_id is None:\n    detections = tracker.update_with_detections(detections)","typeGuard":"def has_tracker_id(d) -> bool:\n    return d.tracker_id is not None and len(d.tracker_id) == len(d)","tryCatchPattern":null,"preventionTips":["Always run tracker.update_with_detections before any trace-based annotation.","Include tracker_id in synthetic test fixtures."],"tags":["tracking","annotators"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}