sgl-project/sglang · error · ValueError

--gpu-ids contains a non-integer GPU id: {token}

Error message

--gpu-ids contains a non-integer GPU id: {token}

What it means

Thrown by normalize_gpu_ids when a token in the --gpu-ids argument cannot be parsed as an integer via int(). It indicates the GPU id list contains a non-numeric token, e.g. '0,x,1' or an empty segment from a trailing comma. The original ValueError from int() is chained as the cause.

Source

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

    if gpu_ids is None:
        return None
    if isinstance(gpu_ids, str):
        values = [gpu_ids]
    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:

View on GitHub (pinned to 0132848349)

Solutions

1. Fix the --gpu-ids value so every comma-separated token is a plain non-negative integer (e.g. --gpu-ids 0,1,2)
2. Check for stray commas, spaces, or shell variable expansion issues (empty vars) in the argument
3. Validate the string with a small pre-parse check before launching the runtime

Example fix

# before
--gpu-ids 0,foo,2
# after
--gpu-ids 0,1,2

def valid_gpu_ids(s: str) -> bool:
    return all(t.strip().lstrip("+").isdigit() for t in s.split(",") if t != "" ) and all(t.strip() for t in s.split(","))

try:
    cfg = PoolConfig(gpu_ids=args.gpu_ids)
except ValueError as e:
    if "non-integer GPU id" in str(e):
        sys.exit(f"Bad --gpu-ids {args.gpu_ids!r}: {e}")
    raise

When it happens

Trigger: Passing --gpu-ids "0,foo" or "0,,1" or "gpu0" to the multimodal_gen runtime, whose config __post_init__ calls normalize_gpu_ids which does int(token) on each comma-separated token.

Common situations: Typo in a CLI flag or shell variable expansion producing an empty/garbage token (e.g. unset $GPU_IDS yielding '--gpu-ids ,'), copy-pasting CUDA_VISIBLE_DEVICES-style values with extra text.

Related errors

• --gpu-ids GPU ids must be non-negative: {gpu_id}
• --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/c739da4a7ca6fb4e. Report an issue: GitHub.