sgl-project/sglang · error · ValueError

--sidecar-args requires --sidecar.

Error message

--sidecar-args requires --sidecar.

What it means

SGLang's --sidecar-args option (a JSON array of extra args passed to a gRPC sidecar process) is only meaningful together with --sidecar. Config resolution rejects sidecar args when no sidecar command was given.

Source

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

        if cfg.grpc_port is not None:
            if not (1 <= cfg.grpc_port <= 65535):
                raise ValueError(
                    "--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 "

View on GitHub (pinned to 0132848349)

Solutions

1. Add a --sidecar value, e.g. --sidecar "python sidecar.py" --sidecar-args '["--port","9000"]'
2. Remove --sidecar-args if no sidecar is intended

Example fix

# before
--sidecar-args '["--port=9000"]'
# after
--sidecar "python sidecar.py" --sidecar-args '["--port=9000"]'

if args.get("sidecar_args") and not args.get("sidecar"):
    raise SystemExit("--sidecar-args requires --sidecar; add it or drop sidecar_args")

When it happens

Trigger: Passing --sidecar-args '["--verbose"]' on the command line without also passing --sidecar "<command>", then launching the server or resolving ServerArgs.

Common situations: Splitting a working launch command into a template and forgetting the --sidecar flag; disabling the sidecar temporarily but leaving its args in the config file.

Related errors

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

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