sgl-project/sglang · error · ValueError

--swa-full-tokens-ratio should be in range (0, 1.0].

Error message

--swa-full-tokens-ratio should be in range (0, 1.0].

What it means

This ValueError is raised during ServerArgs validation when the effective SWA/full attention tokens ratio falls outside (0, 1.0]. The check runs on the *resolved* value because model branches may reset it (e.g. Step3p forces 1.0 under hierarchical cache), superseding user input before it takes effect.

Source

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

                raise ValueError(
                    "The argument disaggregation-decode-enable-offload-kvcache is only supported for decode side."
                )
            if cfg.hicache_storage_backend is None:
                raise ValueError(
                    "The argument disaggregation-decode-enable-offload-kvcache is only supported when hicache-storage-backend is provided."
                )
            if cfg.disaggregation_decode_retraction_backup == "host_pool":
                raise ValueError(
                    "The arguments disaggregation-decode-enable-offload-kvcache and "
                    "disaggregation-decode-retraction-backup=host_pool are mutually exclusive: "
                    "both build a decode host pool."
                )

        # Validate the effective ratio: model branches may declare a reset
        # (e.g. Step3p forces 1.0 under hierarchical cache) that supersedes
        # the user input before it ever takes effect.
        if not (0 < self._resolved().swa_full_tokens_ratio <= 1.0):
            raise ValueError("--swa-full-tokens-ratio should be in range (0, 1.0].")

    def _handle_deterministic_inference(self):
        cfg = resolving_view(self)
        if cfg.rl_on_policy_target is not None:
            logger.warning(
                "Enable deterministic inference because of rl_on_policy_target."
            )
            self._declare(
                "_handle_deterministic_inference",
                enable_deterministic_inference=True,
            )

            # For VLM
            envs.SGLANG_VLM_CACHE_SIZE_MB.set(0)
            # TODO remove this environment variable as a whole
            envs.SGLANG_ENABLE_DETERMINISTIC_INFERENCE.set(True)

        if cfg.enable_deterministic_inference:

View on GitHub (pinned to 0132848349)

Solutions

1. Set --swa-full-tokens-ratio to a value in (0, 1.0], e.g. 0.8 or 1.0
2. If you intended full-token cache, use 1.0 explicitly
3. If using a custom model that overrides the ratio, check its resolution branch sets a valid value

Example fix

# before
python -m sglang.launch_server --swa-full-tokens-ratio 0
# after
python -m sglang.launch_server --swa-full-tokens-ratio 1.0

ratio = args.swa_full_tokens_ratio
if args.swa_full_tokens_ratio is not None and not (0 < ratio <= 1.0):
    raise SystemExit(f"invalid swa_full_tokens_ratio: {ratio}; must be in (0, 1.0]")

When it happens

Trigger: Launching the server with --swa-full-tokens-ratio 0, a negative value, or a value > 1.0; or a model-specific resolution layer producing an out-of-range effective ratio.

Common situations: Setting --swa-full-tokens-ratio 0 expecting to disable full attention; copy-pasting a ratio > 1 from another config; a custom model branch overriding the ratio incorrectly.

Related errors

• Decode context parallel size (--dcp-size / --decode-context-
• --mamba-max-states-per-path must be -1 (unlimited) or a posi
• --asr-max-buffer-seconds must be positive (got {cfg.asr_max_
• --asr-max-concurrent-sessions must be positive (got {cfg.asr
• --prefill-decode-interval must be non-negative.

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