{"record":{"id":"9c2b6115bd1d6bcd","repo":"sgl-project/sglang","slug":"sidecar-args-must-be-a-json-array-of-strings","errorCode":null,"errorMessage":"--sidecar-args must be a JSON array of strings.","messagePattern":"--sidecar-args must be a JSON array of strings\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":4519,"sourceCode":"                    \"--grpc-port / SGLANG_GRPC_PORT \"\n                    f\"({cfg.grpc_port}) must be between 1 and 65535\"\n                )\n            if cfg.grpc_worker_threads is not None and cfg.grpc_worker_threads < 1:\n                raise ValueError(\n                    \"SGLANG_GRPC_WORKER_THREADS \"\n                    f\"({cfg.grpc_worker_threads}) must be >= 1\"\n                )\n\n        # Native gRPC is incompatible with launch paths it doesn't wire into.\n        # Legacy takes precedence over grpc_port, keeping re-runs idempotent.\n        native_grpc = cfg.grpc_port is not None and not legacy_grpc\n        if cfg.sidecar_args is not None:\n            if cfg.sidecar is None:\n                raise ValueError(\"--sidecar-args requires --sidecar.\")\n            if not isinstance(cfg.sidecar_args, list) or not all(\n                isinstance(arg, str) for arg in cfg.sidecar_args\n            ):\n                raise ValueError(\"--sidecar-args must be a JSON array of strings.\")\n        if cfg.sidecar is not None:\n            if not cfg.sidecar.strip():\n                raise ValueError(\"--sidecar must not be empty.\")\n            if legacy_grpc:\n                raise ValueError(\n                    \"--sidecar requires SGLang's native gRPC server; \"\n                    \"it cannot be combined with --smg-grpc-mode/--grpc-mode.\"\n                )\n            if cfg.grpc_port is None:\n                raise ValueError(\"--sidecar requires --grpc-port or SGLANG_GRPC_PORT.\")\n        if native_grpc:\n            if cfg.use_ray:\n                raise ValueError(\n                    \"--grpc-port is not supported with --use-ray: the Ray \"\n                    \"serve launch path does not start the native gRPC server.\"\n                )\n            if cfg.encoder_only:\n                raise ValueError(","sourceCodeStart":4501,"sourceCodeEnd":4537,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L4501-L4537","documentation":"--sidecar-args must deserialize to a JSON array whose elements are all strings; SGLang validates the parsed type during ServerArgs resolution before spawning the sidecar.","triggerScenarios":"Passing --sidecar-args '9000' (a scalar), '[9000]' (numbers), or a non-list JSON object; or shell quoting that collapses the JSON into a bare string.","commonSituations":"Quoting bugs in bash/YAML launch scripts, passing numbers unquoted in JSON, or passing a dict of named args instead of a list.","solutions":["Quote every element as a string: --sidecar-args '[\"--port\",\"9000\"]'","Verify the value parses as a JSON array in Python: json.loads(v) is a list and all(isinstance(a, str) for a in v)","Fix shell escaping (single-quote the whole JSON blob)"],"exampleFix":"# before\n--sidecar-args '[9000, \"--verbose\"]'\n# after\n--sidecar-args '[\"9000\", \"--verbose\"]'","handlingStrategy":"type-guard","validationCode":"import json\nv = json.loads(sidecar_args)\nassert isinstance(v, list) and all(isinstance(a, str) for a in v), \"sidecar_args must be a JSON array of strings\"","typeGuard":"def is_valid_sidecar_args(v) -> bool:\n    return isinstance(v, list) and all(isinstance(a, str) for a in v)","tryCatchPattern":null,"preventionTips":["Single-quote the entire JSON blob in shell commands to avoid word-splitting","Stringify all numeric values inside --sidecar-args"],"tags":["grpc","sidecar","json-validation","config-validation"],"backgroundTag":"json-schema-validation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}