sgl-project/sglang · error · ValueError

must be list or null; got {type(v).__name__}

Error message

must be list or null; got {type(v).__name__}

What it means

Thrown by the field validator for optional 1D/2D int-list fields (e.g. server args like speculative algorithm config). The value is neither None nor a list, so it fails the top-level type check before any element validation.

Source

Thrown at python/sglang/srt/utils/field_validators.py:66

        return v
    if not isinstance(v[0], int):
        raise ValueError(f"elements must be int; got {type(v[0]).__name__}")
    try:
        array("q", v)
    except (TypeError, OverflowError) as e:
        raise ValueError(f"contains non-int64 element: {e}") from None
    return v


def validate_optional_list_i64_1d_2d(
    v: Any,
) -> list[int] | list[list[int]] | None:
    """Validates type: list[int] | list[list[int]] | None"""
    if v is None:
        # Accept None
        return v
    if not isinstance(v, list):
        raise ValueError(f"must be list or null; got {type(v).__name__}")
    if not v:
        # Accept empty list
        return v
    if isinstance(v[0], int):
        # Accept list[int]
        return validate_list_i64_1d(v)
    if isinstance(v[0], list):
        # Accept list[list[int]]
        for i, row in enumerate(v):
            try:
                validate_list_i64_1d(row)
            except ValueError as e:
                raise ValueError(f"row {i}: {e}") from None
        return v
    raise ValueError(f"elements must be int or list; got {type(v[0]).__name__}")

View on GitHub (pinned to 0132848349)

Solutions

1. Change the value to a list, e.g. --arg 3 -> --arg 3,1 or --arg [3]
2. If null is intended, pass explicit null/None or omit the field
3. Check the arg's help text / type annotation for list[int] | list[list[int]] | None

Example fix

# before
server_args.speculative_num_steps = 3  # int
# after
server_args.speculative_num_steps = [3]

def is_opt_i64_list(v): return v is None or (isinstance(v, list) and (not v or isinstance(v[0], (int, list))))

def is_opt_i64_1d_2d(v) -> TypeGuard[list[int] | list[list[int]] | None]:
    if v is None or v == []: return True
    return isinstance(v, list) and isinstance(v[0], (int, list))

When it happens

Trigger: Passing a string, int, dict, or tuple to a server argument validated by validate_optional_list_i64_1d_2d, e.g. --speculative-attention-mode 3 or a YAML/JSON config where the field is a scalar instead of a list.

Common situations: CLI flags that look numeric but expect list syntax, JSON configs with a bare number where a list is expected, or passing a tuple from Python code instead of a list.

Related errors

• Invalid component residency assignment: {value!r}
• Invalid component residency assignment: {raw_selector!r}={ra
• elements must be int or list; got {type(v[0]).__name__}
• Unknown type: {type(other)}
• Invalid threshold_type for topk: {threshold_type}. Choose 'q

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