{"record":{"id":"7b87d982a9283165","repo":"roboflow/supervision","slug":"the-tracker-id-field-is-missing-in-the-provided","errorCode":null,"errorMessage":"The `tracker_id` field is missing in the provided detections. See more: https://supervision.roboflow.com/latest/how_to/track_objects","messagePattern":"The `tracker_id` field is missing in the provided detections\\. See more: https://supervision\\.roboflow\\.com/latest/how_to/track_objects","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/annotators/core.py","lineNumber":2239,"sourceCode":"\n            with sv.VideoSink(target_path='...', video_info=video_info) as sink:\n               for frame in frames_generator:\n                   result = model(frame)[0]\n                   detections = sv.Detections.from_ultralytics(result)\n                   detections = tracker.update_with_detections(detections)\n                   annotated_frame = trace_annotator.annotate(\n                       scene=frame.copy(),\n                       detections=detections)\n                   sink.write_frame(frame=annotated_frame)\n            ```\n\n        ![trace-annotator-example](https://media.roboflow.com/\n        supervision-annotator-examples/trace-annotator-example-purple.png)\n        \"\"\"\n        if not isinstance(scene, np.ndarray):\n            return scene\n        if detections.tracker_id is None:\n            raise ValueError(\n                \"The `tracker_id` field is missing in the provided detections.\"\n                \" See more: https://supervision.roboflow.com/latest/how_to/track_objects\"\n            )\n        filtered_detections: Detections = detections[\n            detections.tracker_id != PENDING_TRACK_ID\n        ]  # type: ignore\n\n        self.trace.put(filtered_detections)\n        for detection_idx in range(len(filtered_detections)):\n            tracker_id_val = filtered_detections.tracker_id[detection_idx]  # type: ignore\n            if tracker_id_val is None:\n                continue\n            tracker_id = int(tracker_id_val)\n            color = resolve_color(\n                color=self.color,\n                detections=filtered_detections,\n                detection_idx=detection_idx,\n                color_lookup=self.color_lookup","sourceCodeStart":2221,"sourceCodeEnd":2257,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/annotators/core.py#L2221-L2257","documentation":"Raised by `TraceAnnotator.annotate` when `detections.tracker_id` is None. TraceAnnotator draws object trajectories keyed by tracker id; without ids it cannot maintain per-object history. Note that detections with `PENDING_TRACK_ID` (-1) are filtered out before the trace is updated, but the field itself must exist.","triggerScenarios":"Calling `TraceAnnotator.annotate(scene, detections)` on raw model detections that never went through `sv.ByteTrack().update_with_detections(...)`; annotating detections from a tracker's underlying model callback instead of the tracker output; testing with hand-built Detections that omit `tracker_id`.","commonSituations":"Adding TraceAnnotator to an existing detection-only pipeline without wiring a tracker; frame-loop refactors that reorder annotate before track; per-camera pipelines where only some cameras track but the annotator runs on all.","solutions":["Insert a tracker step and use its returned Detections: `detections = sv.ByteTrack().update_with_detections(detections)`.","If trajectories are not needed, replace TraceAnnotator with BoxAnnotator/Trace-free annotators.","For synthetic tests, construct detections with `tracker_id=np.arange(n)`."],"exampleFix":"# before\ntrace = sv.TraceAnnotator()\nframe = trace.annotate(frame, detections)  # detections never tracked\n\n# after\ntracker = sv.ByteTrack()\ndetections = tracker.update_with_detections(detections)\ntrace = sv.TraceAnnotator()\nframe = trace.annotate(frame, detections)","handlingStrategy":"type-guard","validationCode":"if detections.tracker_id is None:\n    detections = tracker.update_with_detections(detections)\nannotator.annotate(scene, detections)","typeGuard":"def has_tracker_id(d) -> bool:\n    return d.tracker_id is not None","tryCatchPattern":null,"preventionTips":["Construct TraceAnnotator only in pipelines that include a tracker step.","Test annotator pipelines with fixtures that mirror production Detections fields."],"tags":["tracking","annotators","trace"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}