sgl-project/sglang · error · ValueError

--grpc-port is not supported with --use-ray: the Ray serve l

Error message

--grpc-port is not supported with --use-ray: the Ray serve launch path does not start the native gRPC server.

What it means

Native gRPC (--grpc-port) is only wired into SGLang's standard launch path; the Ray serve launch path does not start the gRPC server, so combining --grpc-port with --use-ray is rejected.

Source

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

            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(
                    "--grpc-port is incompatible with --api-key/--admin-api-key: "
                    "the native gRPC listener bypasses HTTP auth middleware."
                )

View on GitHub (pinned to 0132848349)

Solutions

1. Remove --grpc-port / unset SGLANG_GRPC_PORT when using --use-ray
2. Expose gRPC via your own Ray serve deployment or use the HTTP entrypoint instead

Example fix

# before
--use-ray --grpc-port 50051
# after
--use-ray

if args.get("use_ray") and (args.get("grpc_port") or os.environ.get("SGLANG_GRPC_PORT")):
    raise SystemExit("--grpc-port is unsupported with --use-ray; unset it")

When it happens

Trigger: Passing --use-ray together with --grpc-port (or SGLANG_GRPC_PORT) in ServerArgs.

Common situations: Copying a single-node gRPC launch command onto a Ray cluster deployment, or a shared config template that sets SGLANG_GRPC_PORT globally.

Related errors

• --sidecar requires SGLang's native gRPC server; it cannot be
• --grpc-port is not supported with --encoder-only: encoder di
• SGLANG_GRPC_WORKER_THREADS ({cfg.grpc_worker_threads}) must
• --sidecar-args requires --sidecar.
• --sidecar-args must be a JSON array of strings.

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