sgl-project/sglang · error · ValueError

Invalid disaggregation_mode={cfg.disaggregation_mode!r}

Error message

Invalid disaggregation_mode={cfg.disaggregation_mode!r}

What it means

ServerArgs validation error raised when --disaggregation-mode is given a value outside the allowed set (null, prefill, decode). PD (prefill-decode) disaggregation in SGLang requires each server instance to declare its role explicitly.

Source

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

                "MNNVL All-to-All kernel, which requires an NVIDIA CUDA platform "
                "with SM90+ and MNNVL fabric memory (e.g. GB200 NVL72). The "
                "authoritative fabric probe runs at model-runner init; use 'a2a' "
                "or 'ag_rs' on clusters without MNNVL."
            )
        if cfg.dcp_replicate_q_proj:
            if cfg.dcp_size <= 1:
                raise ValueError("--dcp-replicate-q-proj requires --dcp-size > 1.")
            if cfg.dcp_comm_backend not in ("a2a", "fi_a2a"):
                raise ValueError(
                    "--dcp-replicate-q-proj only applies to the a2a/fi_a2a DCP "
                    "communication backend (it removes the head-dim Q all-gather); "
                    f"got --dcp-comm-backend={cfg.dcp_comm_backend}."
                )

    def _handle_load_balance_method(self):
        cfg = resolving_view(self)
        if cfg.disaggregation_mode not in ("null", "prefill", "decode"):
            raise ValueError(f"Invalid disaggregation_mode={cfg.disaggregation_mode!r}")

        if cfg.load_balance_method == "auto":
            # Default behavior:
            # - non-PD: round_robin
            # - PD prefill: follow_bootstrap_room
            # - PD decode: round_robin
            self._declare(
                "_handle_load_balance_method",
                load_balance_method=(
                    "follow_bootstrap_room"
                    if cfg.disaggregation_mode == "prefill"
                    else "round_robin"
                ),
            )
            return

    def _handle_ssl_validation(self):
        """Ensure SSL arguments are consistent and referenced files exist."""

View on GitHub (pinned to 0132848349)

Solutions

1. Use exactly one of: null (no disaggregation), prefill, or decode
2. Check the variable expansion in your launch script (e.g. empty $DISAGG_MODE)

Example fix

# before
python -m sglang.launch_server --disaggregation-mode prefil
# after
python -m sglang.launch_server --disaggregation-mode prefill

VALID_DISAGG = {"null", "prefill", "decode"}

def normalize_disaggregation_mode(mode: str) -> str:
    m = (mode or "null").strip().lower()
    if m not in VALID_DISAGG:
        raise ValueError(f"disaggregation_mode must be one of {sorted(VALID_DISAGG)}, got {mode!r}")
    return m

def is_valid_disaggregation_mode(mode: str) -> bool:
    return isinstance(mode, str) and mode.strip().lower() in {"null", "prefill", "decode"}

When it happens

Trigger: Passing --disaggregation-mode with a typo or unsupported value, e.g. 'Prefill', 'both', 'pd', 'none', or an empty string.

Common situations: Typos and casing mistakes; older SGLang versions or other frameworks using different mode names (e.g. vLLM-style values); scripting that interpolates an unset variable yielding an empty string.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• MiniMaxH3Pipeline only supports monolithic deployment; disag
• Pi05Pipeline v1 supports same-process execution only. Use pr
• MiniCPM sparse attention does not support PD disaggregation
• PD decode DCP requires --disaggregation-transfer-backend moo
• PD decode DCP currently requires chunk cache; --disaggregati

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