{"record":{"id":"f6b4edce761aa83e","repo":"sgl-project/sglang","slug":"must-be-list-or-null-got-type-v-name","errorCode":null,"errorMessage":"must be list or null; got {type(v).__name__}","messagePattern":"must be list or null; got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/utils/field_validators.py","lineNumber":66,"sourceCode":"        return v\n    if not isinstance(v[0], int):\n        raise ValueError(f\"elements must be int; got {type(v[0]).__name__}\")\n    try:\n        array(\"q\", v)\n    except (TypeError, OverflowError) as e:\n        raise ValueError(f\"contains non-int64 element: {e}\") from None\n    return v\n\n\ndef validate_optional_list_i64_1d_2d(\n    v: Any,\n) -> list[int] | list[list[int]] | None:\n    \"\"\"Validates type: list[int] | list[list[int]] | None\"\"\"\n    if v is None:\n        # Accept None\n        return v\n    if not isinstance(v, list):\n        raise ValueError(f\"must be list or null; got {type(v).__name__}\")\n    if not v:\n        # Accept empty list\n        return v\n    if isinstance(v[0], int):\n        # Accept list[int]\n        return validate_list_i64_1d(v)\n    if isinstance(v[0], list):\n        # Accept list[list[int]]\n        for i, row in enumerate(v):\n            try:\n                validate_list_i64_1d(row)\n            except ValueError as e:\n                raise ValueError(f\"row {i}: {e}\") from None\n        return v\n    raise ValueError(f\"elements must be int or list; got {type(v[0]).__name__}\")\n","sourceCodeStart":48,"sourceCodeEnd":82,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/utils/field_validators.py#L48-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Change the value to a list, e.g. --arg 3 -> --arg 3,1 or --arg [3]","If null is intended, pass explicit null/None or omit the field","Check the arg's help text / type annotation for list[int] | list[list[int]] | None"],"exampleFix":"# before\nserver_args.speculative_num_steps = 3  # int\n# after\nserver_args.speculative_num_steps = [3]","handlingStrategy":"type-guard","validationCode":"def is_opt_i64_list(v): return v is None or (isinstance(v, list) and (not v or isinstance(v[0], (int, list))))","typeGuard":"def is_opt_i64_1d_2d(v) -> TypeGuard[list[int] | list[list[int]] | None]:\n    if v is None or v == []: return True\n    return isinstance(v, list) and isinstance(v[0], (int, list))","tryCatchPattern":null,"preventionTips":["Type config fields as list[int] | list[list[int]] | None in your launcher code","Parse CLI strings into lists before passing to server args"],"tags":["validation","config","type-error"],"backgroundTag":"config-field-type-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}