sgl-project/sglang · error · ValueError

scheduler_rpc_timeout must be None or an integer between 1 a

Error message

scheduler_rpc_timeout must be None or an integer between 1 and {MAX_SCHEDULER_RPC_TIMEOUT_S} seconds

What it means

_validate_scheduler_rpc_timeout requires scheduler_rpc_timeout to be None or a Python int in the range 1..MAX_SCHEDULER_RPC_TIMEOUT_S (bools are explicitly rejected because bool is a subclass of int).

Source

Thrown at python/sglang/multimodal_gen/runtime/server_args/server_args.py:599

        if self.lora_alpha is not None and self.lora_alpha <= 0:
            raise ValueError("lora_alpha must be a positive integer")
        if not current_platform.is_cpu():
            self._validate_parallelism()
        self._validate_cfg_parallel()
        self._validate_batching()
        self._validate_breakable_cuda_graph()
        self.pipeline_config.validate_server_args(self)

    def _validate_scheduler_rpc_timeout(self) -> None:
        timeout = self.scheduler_rpc_timeout
        if timeout is None:
            return
        if (
            not isinstance(timeout, int)
            or isinstance(timeout, bool)
            or not 0 < timeout <= MAX_SCHEDULER_RPC_TIMEOUT_S
        ):
            raise ValueError(
                "scheduler_rpc_timeout must be None or an integer between "
                f"1 and {MAX_SCHEDULER_RPC_TIMEOUT_S} seconds"
            )

    def resolved_bcg_text_buckets(self) -> tuple[int, ...]:
        """Sorted, de-duplicated, positive BCG text buckets.

        Falls back to :data:`DEFAULT_BCG_TEXT_BUCKETS` when ``--bcg-text-buckets``
        is unset, so both prompt padding and warmup capture share one source of
        truth instead of the legacy ``SGLANG_BCG_TEXT_BUCKETS`` env var.
        """
        raw = self.bcg_text_buckets
        if not raw:
            return DEFAULT_BCG_TEXT_BUCKETS
        buckets = sorted({int(b) for b in raw if int(b) > 0})
        return tuple(buckets) or DEFAULT_BCG_TEXT_BUCKETS

    def _validate_breakable_cuda_graph(self):

View on GitHub (pinned to 0132848349)

Solutions

1. Pass None for the default or an int between 1 and MAX_SCHEDULER_RPC_TIMEOUT_S
2. Coerce types explicitly: int(value) when loading from env/config
3. If you need a longer timeout than the max, reduce scheduler load (smaller batch, fewer ranks) instead of exceeding the cap

Example fix

# before
ServerArgs(..., scheduler_rpc_timeout="30")
# after
ServerArgs(..., scheduler_rpc_timeout=30)

t = cfg.get('scheduler_rpc_timeout')
assert t is None or (isinstance(t, int) and not isinstance(t, bool) and 1 <= t <= MAX_SCHEDULER_RPC_TIMEOUT_S), 'bad scheduler_rpc_timeout'

def valid_rpc_timeout(v) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and 1 <= v <= MAX_SCHEDULER_RPC_TIMEOUT_S)

When it happens

Trigger: Passing scheduler_rpc_timeout=0, a negative number, a float like 2.5, a string like '30', a value above MAX_SCHEDULER_RPC_TIMEOUT_S, or True/False.

Common situations: Parsing the timeout from an env var or YAML as a string/float; setting a very large timeout for slow distributed setups; accidentally passing a flag boolean.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• shift must be positive
• {beta_schedule} is not implemented for {self.__class__}
• Waiting for main node timeout!
• DeepGEMM Kernels compilation timeout.\n\nFeel free and pleas
• bad compress_ratio {compress_ratio}

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