sgl-project/sglang · error · ValueError

--grpc-port is not supported with --encoder-only: encoder di

Error message

--grpc-port is not supported with --encoder-only: encoder disaggregation uses its own server.

What it means

Encoder-only deployments use SGLang's encoder disaggregation server, which has its own serving stack; the native gRPC listener is not integrated, so --grpc-port plus --encoder-only is rejected during ServerArgs resolution.

Source

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

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

    def _handle_prefill_delayer_env_compat(self):
        if envs.SGLANG_SCHEDULER_DECREASE_PREFILL_IDLE.get():
            self._declare(
                "_handle_prefill_delayer_env_compat",

View on GitHub (pinned to 0132848349)

Solutions

1. Remove --grpc-port / unset SGLANG_GRPC_PORT for encoder-only deployments
2. Use the encoder disaggregation server's own interface

Example fix

# before
--encoder-only --grpc-port 50051
# after
--encoder-only

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

When it happens

Trigger: Passing --encoder-only together with --grpc-port or SGLANG_GRPC_PORT.

Common situations: Reusing a decoding-server gRPC launch command for an encoder deployment; global SGLANG_GRPC_PORT leaking into encoder worker pods.

Related errors

• --sidecar requires SGLang's native gRPC server; it cannot be
• --grpc-port is not supported with --use-ray: the Ray serve l
• 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/8fbea4cd49f3ddb1. Report an issue: GitHub.