roboflow/supervision · error · ValueError

max_line_length must be a positive integer

Error message

max_line_length must be a positive integer

What it means

Raised by the text-wrapping helper in supervision.annotators.utils (used for label text) when max_line_length is set but is <= 0. The value is passed to textwrap.wrap as a width, which requires a positive integer; supervision validates it first so the failure names the right parameter instead of surfacing from textwrap internals.

Source

Thrown at src/supervision/annotators/utils.py:192

    Args:
        text: The text (or object) to wrap.
        max_line_length: Maximum width for each wrapped line.

    Returns:
        Wrapped lines.
    """

    if not text:
        return [""]

    if not isinstance(text, str):
        text = str(text)

    if max_line_length is None:
        return text.splitlines() or [""]

    if max_line_length <= 0:
        raise ValueError("max_line_length must be a positive integer")

    paragraphs = text.split("\n")
    all_lines: list[str] = []

    for paragraph in paragraphs:
        if paragraph == "":
            all_lines.append("")
            continue

        wrapped = textwrap.wrap(
            paragraph,
            width=max_line_length,
            break_long_words=True,
            replace_whitespace=False,
            drop_whitespace=True,
        )

        all_lines.extend(wrapped or [""])

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass None instead of 0 to disable wrapping entirely.
2. Clamp derived values: max_line_length=max(1, computed).
3. Validate config before constructing annotators if the value comes from user input.
4. For tiny images, skip labels or use a fixed minimum like 8 characters.

Example fix

// before
mll = image_width // 100  # 0 for 80px image
label_annotator = sv.LabelAnnotator(... )
wrap(text, max_line_length=mll)

// after
mll = max(8, image_width // 100)
wrap(text, max_line_length=mll)

if max_line_length is not None:
    max_line_length = max(1, int(max_line_length))

# or disable wrapping entirely
wrapped = wrap(text, max_line_length=None)

When it happens

Trigger: Constructing a LabelAnnotator (or calling the wrap helper) with text_scale/thickness-derived max_line_length that computes to 0 or negative on tiny values; passing max_line_length=0 hoping to disable wrapping; deriving the value from image width where a 0-width input sneaks in.

Common situations: Auto-scaling label sizes for very small images (e.g. 32px thumbnails) where int(scale * width) rounds to 0; configuration arithmetic like max_line_length = width // 100 with width < 100; users assuming 0 or -1 means 'unlimited'.

Related errors

• Unsupported color lookup strategy: {color_lookup}
• roundness attribute must be float between (0, 1.0]
• `slice_wh` must be an int or a tuple of two positive integer
• `overlap_wh` must be an int or a tuple of two non negative i
• `thread_workers` must be a positive integer. Received: {thre

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