{"record":{"id":"179e784ec58a5bba","repo":"sgl-project/sglang","slug":"invalid-disaggregation-mode-cfg-disaggregation-mo","errorCode":null,"errorMessage":"Invalid disaggregation_mode={cfg.disaggregation_mode!r}","messagePattern":"Invalid disaggregation_mode=(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":4289,"sourceCode":"                \"MNNVL All-to-All kernel, which requires an NVIDIA CUDA platform \"\n                \"with SM90+ and MNNVL fabric memory (e.g. GB200 NVL72). The \"\n                \"authoritative fabric probe runs at model-runner init; use 'a2a' \"\n                \"or 'ag_rs' on clusters without MNNVL.\"\n            )\n        if cfg.dcp_replicate_q_proj:\n            if cfg.dcp_size <= 1:\n                raise ValueError(\"--dcp-replicate-q-proj requires --dcp-size > 1.\")\n            if cfg.dcp_comm_backend not in (\"a2a\", \"fi_a2a\"):\n                raise ValueError(\n                    \"--dcp-replicate-q-proj only applies to the a2a/fi_a2a DCP \"\n                    \"communication backend (it removes the head-dim Q all-gather); \"\n                    f\"got --dcp-comm-backend={cfg.dcp_comm_backend}.\"\n                )\n\n    def _handle_load_balance_method(self):\n        cfg = resolving_view(self)\n        if cfg.disaggregation_mode not in (\"null\", \"prefill\", \"decode\"):\n            raise ValueError(f\"Invalid disaggregation_mode={cfg.disaggregation_mode!r}\")\n\n        if cfg.load_balance_method == \"auto\":\n            # Default behavior:\n            # - non-PD: round_robin\n            # - PD prefill: follow_bootstrap_room\n            # - PD decode: round_robin\n            self._declare(\n                \"_handle_load_balance_method\",\n                load_balance_method=(\n                    \"follow_bootstrap_room\"\n                    if cfg.disaggregation_mode == \"prefill\"\n                    else \"round_robin\"\n                ),\n            )\n            return\n\n    def _handle_ssl_validation(self):\n        \"\"\"Ensure SSL arguments are consistent and referenced files exist.\"\"\"","sourceCodeStart":4271,"sourceCodeEnd":4307,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L4271-L4307","documentation":"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.","triggerScenarios":"Passing --disaggregation-mode with a typo or unsupported value, e.g. 'Prefill', 'both', 'pd', 'none', or an empty string.","commonSituations":"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.","solutions":["Use exactly one of: null (no disaggregation), prefill, or decode","Check the variable expansion in your launch script (e.g. empty $DISAGG_MODE)"],"exampleFix":"# before\npython -m sglang.launch_server --disaggregation-mode prefil\n# after\npython -m sglang.launch_server --disaggregation-mode prefill","handlingStrategy":"validation","validationCode":"VALID_DISAGG = {\"null\", \"prefill\", \"decode\"}\n\ndef normalize_disaggregation_mode(mode: str) -> str:\n    m = (mode or \"null\").strip().lower()\n    if m not in VALID_DISAGG:\n        raise ValueError(f\"disaggregation_mode must be one of {sorted(VALID_DISAGG)}, got {mode!r}\")\n    return m","typeGuard":"def is_valid_disaggregation_mode(mode: str) -> bool:\n    return isinstance(mode, str) and mode.strip().lower() in {\"null\", \"prefill\", \"decode\"}","tryCatchPattern":null,"preventionTips":["Normalize the value (strip/lowercase) before passing it to the CLI","Guard against empty env-var expansion in launch scripts with ${VAR:-null}"],"tags":["sglang","disaggregation","pd-disaggregation","argument-validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}