roboflow/supervision · error · ValueError

The `tracker_id` field is missing in the provided detections

Error message

The `tracker_id` field is missing in the provided detections. See more: https://supervision.roboflow.com/latest/how_to/track_objects

What it means

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.

Source

Thrown at src/supervision/annotators/core.py:2239

            with sv.VideoSink(target_path='...', video_info=video_info) as sink:
               for frame in frames_generator:
                   result = model(frame)[0]
                   detections = sv.Detections.from_ultralytics(result)
                   detections = tracker.update_with_detections(detections)
                   annotated_frame = trace_annotator.annotate(
                       scene=frame.copy(),
                       detections=detections)
                   sink.write_frame(frame=annotated_frame)
            ```

        ![trace-annotator-example](https://media.roboflow.com/
        supervision-annotator-examples/trace-annotator-example-purple.png)
        """
        if not isinstance(scene, np.ndarray):
            return scene
        if detections.tracker_id is None:
            raise ValueError(
                "The `tracker_id` field is missing in the provided detections."
                " See more: https://supervision.roboflow.com/latest/how_to/track_objects"
            )
        filtered_detections: Detections = detections[
            detections.tracker_id != PENDING_TRACK_ID
        ]  # type: ignore

        self.trace.put(filtered_detections)
        for detection_idx in range(len(filtered_detections)):
            tracker_id_val = filtered_detections.tracker_id[detection_idx]  # type: ignore
            if tracker_id_val is None:
                continue
            tracker_id = int(tracker_id_val)
            color = resolve_color(
                color=self.color,
                detections=filtered_detections,
                detection_idx=detection_idx,
                color_lookup=self.color_lookup

View on GitHub (pinned to 7f254d9784)

Solutions

1. Insert a tracker step and use its returned Detections: `detections = sv.ByteTrack().update_with_detections(detections)`.
2. If trajectories are not needed, replace TraceAnnotator with BoxAnnotator/Trace-free annotators.
3. For synthetic tests, construct detections with `tracker_id=np.arange(n)`.

Example fix

# before
trace = sv.TraceAnnotator()
frame = trace.annotate(frame, detections)  # detections never tracked

# after
tracker = sv.ByteTrack()
detections = tracker.update_with_detections(detections)
trace = sv.TraceAnnotator()
frame = trace.annotate(frame, detections)

if detections.tracker_id is None:
    detections = tracker.update_with_detections(detections)
annotator.annotate(scene, detections)

def has_tracker_id(d) -> bool:
    return d.tracker_id is not None

When it happens

Trigger: 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`.

Common situations: 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.

Related errors

• Could not put detections into Trace because Detections do no
• Could not resolve color by track because Detections do not h
• tracker_id must be a 1D np.ndarray with shape {expected_shap
• Unsupported image type: {type(scene)}
• Unsupported color lookup strategy: {color_lookup}

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