sgl-project/sglang · error · ValueError
--gpu-ids GPU ids must be non-negative
Error message
--gpu-ids GPU ids must be non-negative: {gpu_id} What it means
--gpu-ids entries must be non-negative integers. Fix the offending GPU id.
Solutions
- Use only non-negative GPU ordinals (device indices as seen by CUDA), e.g. --gpu-ids 0,1
- To exclude GPUs, enumerate the ones you want rather than using negative ids
- 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
Defensive patterns
Strategy: validation
Validate before calling
ids = [int(t) for t in gpu_ids_str.split(",")]
assert all(i >= 0 for i in ids), f"negative gpu id in {ids}" Prevention
- Never use negative notation for GPU exclusion; enumerate wanted GPUs explicitly
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.
Understand the failure class
Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.
Related errors
- --gpu-ids contains a non-integer GPU id
- --gpu-ids contains duplicate GPU ids
- a port must be specified in IPv6 address (format…
- A tokenizer is required to load an external ngram corpus.
- action_mode is set but the loaded Cosmos3 checkpoint has no…
AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28).
Data as JSON: /api/errors/ee1d39ffcab1c67a.
Report an issue: GitHub.
Appendix: 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)