roboflow/supervision · error · ValueError

Unsupported position: {position}

Error message

Unsupported position: {position}

What it means

Raised by a static position-resolution helper in `PercentageBarAnnotator` when the supplied `position` is not one of the handled `sv.Position` members (TOP_LEFT, TOP_RIGHT, CENTER, CENTER_LEFT, CENTER_RIGHT, BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT). The if/elif chain exhausts the known enum values and raises for anything else — normally only reachable with a non-enum value.

Source

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

            return (cx - width // 2, cy), (cx + width // 2, cy - height)
        elif position == Position.TOP_RIGHT:
            return (cx, cy), (cx + width, cy - height)
        elif position == Position.CENTER_LEFT:
            return (cx - width, cy - height // 2), (cx, cy + height // 2)
        elif position == Position.CENTER or position == Position.CENTER_OF_MASS:
            return (
                (cx - width // 2, cy - height // 2),
                (cx + width // 2, cy + height // 2),
            )
        elif position == Position.CENTER_RIGHT:
            return (cx, cy - height // 2), (cx + width, cy + height // 2)
        elif position == Position.BOTTOM_LEFT:
            return (cx - width, cy), (cx, cy + height)
        elif position == Position.BOTTOM_CENTER:
            return (cx - width // 2, cy), (cx + width // 2, cy + height)
        elif position == Position.BOTTOM_RIGHT:
            return (cx, cy), (cx + width, cy + height)
        raise ValueError(f"Unsupported position: {position}")

    @staticmethod
    def _validate_custom_values(
        custom_values: npt.NDArray[np.float64] | list[float] | None,
        detections: Detections,
    ) -> None:
        if custom_values is None:
            if detections.confidence is None:
                raise ValueError(
                    "The provided detections do not contain confidence values. "
                    "Please provide `custom_values` or ensure that the detections "
                    "contain confidence values (e.g. by using a different model)."
                )

        else:
            if not isinstance(custom_values, (np.ndarray, list)):
                raise TypeError(
                    "custom_values must be either a numpy array or a list of floats."

View on GitHub (pinned to 7f254d9784)

Solutions

1. Convert config strings to the enum before constructing: `sv.Position[str.upper()]` or a mapping dict.
2. Pin/upgrade supervision so the installed version knows every Position member you use.
3. Check the value is a member first: `assert position in sv.Position.__members__.values()` or use `sv.Position(position)` which validates.

Example fix

# before
annotator = sv.PercentageBarAnnotator(position="BOTTOM_CENTER")  # str, not enum -> ValueError

# after
annotator = sv.PercentageBarAnnotator(position=sv.Position.BOTTOM_CENTER)

position = position if isinstance(position, sv.Position) else sv.Position[str(position).upper()]

def as_position(v) -> sv.Position:
    if isinstance(v, sv.Position):
        return v
    try:
        return sv.Position[str(v).upper()]
    except KeyError:
        raise ValueError(f"unknown position: {v!r}") from None

When it happens

Trigger: Passing a raw string like `position="BOTTOM"` (not the enum `sv.Position.BOTTOM_CENTER`) to the PercentageBarAnnotator constructor; passing a custom int or a mock object as position; passing `None`. The enum comparison uses equality, so unmatched values fall through every branch to the raise.

Common situations: Loading annotator config from JSON/YAML where position arrives as a string and is not converted with `sv.Position(...)`; using a Position member added in a newer supervision version while running an older version that lacks a branch for it; typos in position names in config files.

Related errors

• Unsupported position: {position}
• {anchor} is not supported.
• {anchor} is not supported.
• Unsupported color lookup strategy: {color_lookup}
• Invalid asset. It should be one of the following: {valid_ass

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