sgl-project/sglang · error · ValueError

--sidecar requires SGLang's native gRPC server; it cannot be

Error message

--sidecar requires SGLang's native gRPC server; it cannot be combined with --smg-grpc-mode/--grpc-mode.

What it means

The --sidecar feature is wired into SGLang's native gRPC server only; it cannot be used with the legacy gRPC mode flags (--smg-grpc-mode / --grpc-mode), whose launch path never starts a sidecar.

Source

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

                    "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(
                    "--grpc-port is not supported with --encoder-only: "
                    "encoder disaggregation uses its own server."
                )
            if cfg.tokenizer_worker_num > 1:
                raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

1. Remove --grpc-mode / --smg-grpc-mode and use native gRPC via --grpc-port
2. Or drop --sidecar if legacy grpc mode is required

Example fix

# before
--grpc-mode --sidecar "python sidecar.py"
# after
--grpc-port 50051 --sidecar "python sidecar.py"

legacy = args.get("grpc_mode") or args.get("smg_grpc_mode")
if legacy and args.get("sidecar"):
    raise SystemExit("sidecar requires native gRPC (--grpc-port); remove --grpc-mode/--smg-grpc-mode")

When it happens

Trigger: Passing both --grpc-mode (or --smg-grpc-mode) and --sidecar in the same ServerArgs.

Common situations: Migrating an old deployment from legacy grpc mode to native gRPC and leaving the old mode flag in the command line; combining flags from two different docs pages.

Related errors

• --sidecar-args requires --sidecar.
• --sidecar-args must be a JSON array of strings.
• --sidecar must not be empty.
• --sidecar requires --grpc-port or SGLANG_GRPC_PORT.
• --grpc-port is not supported with --use-ray: the Ray serve l

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