sgl-project/sglang · error · ValueError

--gpu-ids GPU ids must be non-negative: {gpu_id}

Error message

--gpu-ids GPU ids must be non-negative: {gpu_id}

What it means

Thrown by normalize_gpu_ids when a parsed GPU id is negative. GPU ordinals are non-negative, so a token like -1 fails validation immediately after int() succeeds.

Source

Thrown at python/sglang/multimodal_gen/runtime/utils/common.py:105

    else:
        values = list(gpu_ids)

    tokens: list[str] = []
    for value in values:
        tokens.extend(part for part in str(value).replace(",", " ").split() if part)
    if not tokens:
        return []

    parsed: list[int] = []
    for token in tokens:
        try:
            gpu_id = int(token)
        except ValueError as exc:
            raise ValueError(
                f"--gpu-ids contains a non-integer GPU id: {token}"
            ) from exc
        if gpu_id < 0:
            raise ValueError(f"--gpu-ids GPU ids must be non-negative: {gpu_id}")
        parsed.append(gpu_id)

    if len(set(parsed)) != len(parsed):
        raise ValueError(f"--gpu-ids contains duplicate GPU ids: {parsed}")
    return parsed


def parse_size(size: str) -> tuple[int | None, int | None]:
    try:
        parts = size.lower().replace(" ", "").split("x")
        if len(parts) != 2:
            raise ValueError
        return int(parts[0]), int(parts[1])
    except ValueError:
        return None, None


def parse_tcp_host_port(value: str | None, field_name: str) -> tuple[str, int]:

View on GitHub (pinned to 0132848349)

Solutions

1. Use only non-negative GPU ordinals (device indices as seen by CUDA), e.g. --gpu-ids 0,1
2. To exclude GPUs, enumerate the ones you want rather than using negative ids
3. If exclusion is genuinely needed, set CUDA_VISIBLE_DEVICES upstream and use the remapped indices

Example fix

# before
--gpu-ids 0,-1
# after
CUDA_VISIBLE_DEVICES=0 --gpu-ids 0

ids = [int(t) for t in gpu_ids_str.split(",")]
assert all(i >= 0 for i in ids), f"negative gpu id in {ids}"

When it happens

Trigger: Passing --gpu-ids "-1" or "0,-3" — int() parses fine but the value fails the gpu_id < 0 check in normalize_gpu_ids (called from config __post_init__).

Common situations: Attempting to express 'exclude GPU 1' with negative notation, or a misconfigured environment variable that contains a leading minus sign.

Related errors

• --gpu-ids contains a non-integer GPU id: {token}
• --gpu-ids contains duplicate GPU ids: {parsed}
• v_cache must be provided
• q can only be None when only_qv=True
• q must be provided unless qv is provided with only_qv=True

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/ee1d39ffcab1c67a. Report an issue: GitHub.