sgl-project/sglang · error · ValueError

--sidecar-args must be a JSON array of strings.

Error message

--sidecar-args must be a JSON array of strings.

What it means

--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.

Source

Thrown at python/sglang/srt/server_args.py:4519

                    "--grpc-port / SGLANG_GRPC_PORT "
                    f"({cfg.grpc_port}) must be between 1 and 65535"
                )
            if cfg.grpc_worker_threads is not None and cfg.grpc_worker_threads < 1:
                raise ValueError(
                    "SGLANG_GRPC_WORKER_THREADS "
                    f"({cfg.grpc_worker_threads}) must be >= 1"
                )

        # Native gRPC is incompatible with launch paths it doesn't wire into.
        # Legacy takes precedence over grpc_port, keeping re-runs idempotent.
        native_grpc = cfg.grpc_port is not None and not legacy_grpc
        if cfg.sidecar_args is not None:
            if cfg.sidecar is None:
                raise ValueError("--sidecar-args requires --sidecar.")
            if not isinstance(cfg.sidecar_args, list) or not all(
                isinstance(arg, str) for arg in cfg.sidecar_args
            ):
                raise ValueError("--sidecar-args must be a JSON array of strings.")
        if cfg.sidecar is not None:
            if not cfg.sidecar.strip():
                raise ValueError("--sidecar must not be empty.")
            if legacy_grpc:
                raise ValueError(
                    "--sidecar requires SGLang's native gRPC server; "
                    "it cannot be combined with --smg-grpc-mode/--grpc-mode."
                )
            if cfg.grpc_port is None:
                raise ValueError("--sidecar requires --grpc-port or SGLANG_GRPC_PORT.")
        if native_grpc:
            if cfg.use_ray:
                raise ValueError(
                    "--grpc-port is not supported with --use-ray: the Ray "
                    "serve launch path does not start the native gRPC server."
                )
            if cfg.encoder_only:
                raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

1. Quote every element as a string: --sidecar-args '["--port","9000"]'
2. 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)
3. Fix shell escaping (single-quote the whole JSON blob)

Example fix

# before
--sidecar-args '[9000, "--verbose"]'
# after
--sidecar-args '["9000", "--verbose"]'

import json
v = json.loads(sidecar_args)
assert isinstance(v, list) and all(isinstance(a, str) for a in v), "sidecar_args must be a JSON array of strings"

def is_valid_sidecar_args(v) -> bool:
    return isinstance(v, list) and all(isinstance(a, str) for a in v)

When it happens

Trigger: 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.

Common situations: Quoting bugs in bash/YAML launch scripts, passing numbers unquoted in JSON, or passing a dict of named args instead of a list.

Related errors

• --sidecar-args requires --sidecar.
• --sidecar must not be empty.
• --sidecar requires SGLang's native gRPC server; it cannot be
• --sidecar requires --grpc-port or SGLANG_GRPC_PORT.
• SGLANG_GRPC_WORKER_THREADS ({cfg.grpc_worker_threads}) must

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