roboflow/supervision · error · ValueError

tracker_id must be a 1D np.ndarray with shape {expected_shap

Error message

tracker_id must be a 1D np.ndarray with shape {expected_shape}, but got shape {actual_shape}

What it means

Raised by supervision.validators._validate_tracker_id when tracker_id is supplied to Detections but is not None and not a 1D np.ndarray of shape (n,) aligned with xyxy. tracker_id carries the object ID assigned by a tracker (ByteTrack/BoT-SORT).

Source

Thrown at src/supervision/validators/__init__.py:176

@deprecated(  # type: ignore[untyped-decorator]
    target=_validate_keypoint_confidence,
    deprecated_in="0.27.0",
    remove_in="0.31.0",
)
def validate_keypoint_confidence(confidence: Any, n: int, m: int) -> None:
    void(confidence, n, m)


def _validate_tracker_id(tracker_id: Any, n: int) -> None:
    expected_shape = f"({n},)"
    actual_shape = str(getattr(tracker_id, "shape", None))
    is_valid = tracker_id is None or (
        isinstance(tracker_id, np.ndarray) and tracker_id.shape == (n,)
    )
    if not is_valid:
        raise ValueError(
            f"tracker_id must be a 1D np.ndarray with shape {expected_shape}, but got "
            f"shape {actual_shape}"
        )


@deprecated(  # type: ignore[untyped-decorator]
    target=_validate_tracker_id,
    deprecated_in="0.29.0",
    remove_in="0.32.0",
)
def validate_tracker_id(tracker_id: Any, n: int) -> None:
    void(tracker_id, n)


def _validate_data(data: dict[str, Any], n: int) -> None:
    for key, value in data.items():
        if isinstance(value, list):
            if len(value) != n:

View on GitHub (pinned to 7f254d9784)

Solutions

1. Convert to 1D NumPy array: tracker_id=np.asarray(ids, dtype=int).
2. Apply identical indexing to xyxy and tracker_id after any filtering: det = det[idx].
3. Prefer using tracker.update(dets) which returns Detections with a valid tracker_id already set.
4. Leave tracker_id=None for untracked detections.

Example fix

# before
dets = Detections(xyxy=boxes, tracker_id=[3, 7])  # list -> ValueError

# after
dets = Detections(xyxy=boxes, tracker_id=np.array([3, 7]))

n = len(xyxy)
tracker_id = None if tracker_id is None else np.asarray(tracker_id).reshape(n)
dets = Detections(xyxy=xyxy, tracker_id=tracker_id)

def is_valid_tracker_id(tracker_id: Any, n: int) -> bool:
    return tracker_id is None or (
        isinstance(tracker_id, np.ndarray) and tracker_id.shape == (n,)
    )

When it happens

Trigger: Passing tracker_id as a Python list of ints, an array of shape (1, n), or an array longer/shorter than xyxy when building Detections manually.

Common situations: Feeding tracker output back into a reconstructed Detections object; keeping ids in a Python list across frames; desynchronizing ids after slicing/filtering detections without applying the same filter to ids.

Related errors

• xyxy must be a 2D np.ndarray with shape {expected_shape}, bu
• class_id must be a 1D np.ndarray with shape {expected_shape}
• confidence must be a 1D np.ndarray with shape {expected_shap
• Detections confidence must be provided for tracking.
• Detections must have class_id attribute.

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