sgl-project/sglang · error · ValueError

--grpc-port is incompatible with --api-key/--admin-api-key:

Error message

--grpc-port is incompatible with --api-key/--admin-api-key: the native gRPC listener bypasses HTTP auth middleware.

What it means

The native gRPC listener bypasses SGLang's HTTP auth middleware, so API keys would not be enforced on the gRPC port. ServerArgs therefore rejects --grpc-port combined with --api-key or --admin-api-key.

Source

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

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

    def _handle_prefill_delayer_env_compat(self):
        if envs.SGLANG_SCHEDULER_DECREASE_PREFILL_IDLE.get():
            self._declare(
                "_handle_prefill_delayer_env_compat",
                enable_prefill_delayer=True,
            )
        if x := envs.SGLANG_PREFILL_DELAYER_MAX_DELAY_PASSES.get():
            self._declare(
                "_handle_prefill_delayer_env_compat",
                prefill_delayer_max_delay_passes=x,
            )
        if x := envs.SGLANG_PREFILL_DELAYER_TOKEN_USAGE_LOW_WATERMARK.get():
            self._declare(
                "_handle_prefill_delayer_env_compat",

View on GitHub (pinned to 0132848349)

Solutions

1. Remove --api-key / --admin-api-key when using native gRPC
2. Or drop --grpc-port and serve over HTTP so auth middleware applies
3. If gRPC is required with auth, front the gRPC port with an authenticating proxy / network policy

Example fix

# before
--grpc-port 50051 --api-key sk-123
# after
--api-key sk-123  # HTTP only

if (args.get("grpc_port") or os.environ.get("SGLANG_GRPC_PORT")) and (args.get("api_key") or args.get("admin_api_key")):
    raise SystemExit("auth keys are incompatible with native gRPC; choose one")

When it happens

Trigger: Passing --api-key and/or --admin-api-key together with --grpc-port or SGLANG_GRPC_PORT.

Common situations: Hardening a deployment with auth keys without realizing gRPC traffic would be unauthenticated; shared security baselines that set --api-key on every instance.

Related errors

• --sidecar requires SGLang's native gRPC server; it cannot be
• --grpc-port is not supported with --use-ray: the Ray serve l
• --grpc-port is not supported with --encoder-only: encoder di
• allow_neg_eigval=True requires 2*sigmoid(beta), which is not
• Crusoe API key required. Pass api_key= or set CRUSOE_API_KEY

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