sgl-project/sglang · error · ValueError

--sidecar requires --grpc-port or SGLANG_GRPC_PORT.

Error message

--sidecar requires --grpc-port or SGLANG_GRPC_PORT.

What it means

A sidecar only makes sense attached to the native gRPC listener, so --sidecar requires that a gRPC port be configured via --grpc-port or SGLANG_GRPC_PORT.

Source

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

        # 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(
                    "Native gRPC does not yet support --tokenizer-worker-num > 1. "
                    "Unset --grpc-port or set --tokenizer-worker-num 1."
                )
            if cfg.api_key or cfg.admin_api_key:
                raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

1. Add --grpc-port <port> (e.g. 50051)
2. Or export SGLANG_GRPC_PORT=<port>
3. Remove --sidecar if gRPC serving is not intended

Example fix

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

import os
if args.get("sidecar") and not (args.get("grpc_port") or os.environ.get("SGLANG_GRPC_PORT")):
    args["grpc_port"] = 50051  # or fail fast

When it happens

Trigger: Passing --sidecar without any --grpc-port flag and without SGLANG_GRPC_PORT in the environment.

Common situations: Assuming the sidecar attaches to the HTTP server; removing the gRPC port while keeping the sidecar during cleanup of a launch script.

Related errors

• --sidecar-args requires --sidecar.
• --sidecar-args must be a JSON array of strings.
• --sidecar must not be empty.
• --sidecar requires SGLang's native gRPC server; it cannot be
• 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/fa556598f9c8c292. Report an issue: GitHub.