sgl-project/sglang · error · ValueError

Native gRPC does not yet support --tokenizer-worker-num > 1.

Error message

Native gRPC does not yet support --tokenizer-worker-num > 1. Unset --grpc-port or set --tokenizer-worker-num 1.

What it means

The native gRPC server currently assumes a single tokenizer worker; launching with --tokenizer-worker-num > 1 and --grpc-port fails validation because multi-tokenizer routing is not yet implemented for gRPC.

Source

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

                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",
                enable_prefill_delayer=True,
            )
        if x := envs.SGLANG_PREFILL_DELAYER_MAX_DELAY_PASSES.get():
            self._declare(
                "_handle_prefill_delayer_env_compat",

View on GitHub (pinned to 0132848349)

Solutions

1. Set --tokenizer-worker-num 1 (the gRPC-supported value)
2. Or unset --grpc-port / SGLANG_GRPC_PORT and use the HTTP path
3. Watch release notes for multi-tokenizer gRPC support

Example fix

# before
--grpc-port 50051 --tokenizer-worker-num 4
# after
--grpc-port 50051 --tokenizer-worker-num 1

if (args.get("grpc_port") or os.environ.get("SGLANG_GRPC_PORT")) and args.get("tokenizer_worker_num", 1) > 1:
    args["tokenizer_worker_num"] = 1  # or fail fast

When it happens

Trigger: Setting --tokenizer-worker-num to 2+ while --grpc-port (or SGLANG_GRPC_PORT) is set.

Common situations: Scaling up tokenizer workers for high HTTP QPS and reusing the same flags on a gRPC deployment; defaults changed in a shared launch profile.

Related errors

• SGLANG_GRPC_WORKER_THREADS ({cfg.grpc_worker_threads}) must
• --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

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