sgl-project/sglang · error · ValueError

SGLANG_GRPC_WORKER_THREADS ({cfg.grpc_worker_threads}) must

Error message

SGLANG_GRPC_WORKER_THREADS ({cfg.grpc_worker_threads}) must be >= 1

What it means

SGLang validates that the native gRPC worker-thread count (SGLANG_GRPC_WORKER_THREADS) is a positive integer. The check runs in ServerArgs config resolution when a gRPC port is configured, since a non-positive thread pool size is meaningless for the gRPC server.

Source

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

            )

        # Legacy SMG defaults its port to --port + 10000. Derive/validate only
        # when gRPC is in use, so HTTP-only high ports don't fail validation.
        legacy_grpc = cfg.smg_grpc_mode or cfg.grpc_mode
        if legacy_grpc and cfg.grpc_port is None:
            self._declare(
                "_handle_deprecated_args",
                grpc_port=cfg.port + 10000,
            )

        if cfg.grpc_port is not None:
            if not (1 <= cfg.grpc_port <= 65535):
                raise ValueError(
                    "--grpc-port / SGLANG_GRPC_PORT "
                    f"({cfg.grpc_port}) must be between 1 and 65535"
                )
            if cfg.grpc_worker_threads is not None and cfg.grpc_worker_threads < 1:
                raise ValueError(
                    "SGLANG_GRPC_WORKER_THREADS "
                    f"({cfg.grpc_worker_threads}) must be >= 1"
                )

        # Native gRPC is incompatible with launch paths it doesn't wire into.
        # 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:

View on GitHub (pinned to 0132848349)

Solutions

Set SGLANG_GRPC_WORKER_THREADS to a positive integer (e.g. 1 or 8), or unset it to use the default
If gRPC is not wanted, unset SGLANG_GRPC_PORT / remove --grpc-port so this validation block is skipped
Check shell profile / CI secrets for a stale SGLANG_GRPC_WORKER_THREADS export

Example fix

# before
export SGLANG_GRPC_WORKER_THREADS=0
# after
export SGLANG_GRPC_WORKER_THREADS=8

Defensive patterns

Strategy: validation

Validate before calling

import os
threads = int(os.environ.get("SGLANG_GRPC_WORKER_THREADS", "0") or 0)
grpc_port = os.environ.get("SGLANG_GRPC_PORT")
if grpc_port and threads < 1:
    os.environ["SGLANG_GRPC_WORKER_THREADS"] = str(max(threads, 8))

Prevention

Never use 0 as a placeholder for SGLANG_GRPC_WORKER_THREADS; unset it instead
Add a config lint step that checks numeric env vars against their documented minimums before launch

When it happens

Trigger: Setting env SGLANG_GRPC_WORKER_THREADS=0 or a negative number while also enabling native gRPC (--grpc-port / SGLANG_GRPC_PORT), then constructing or resolving ServerArgs.

Common situations: Env var typo (e.g. '0' as a placeholder), CI scripts exporting the var globally with a default of 0, or copy-pasted configs from deployments that disabled gRPC workers.

Related errors

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