{"record":{"id":"f7dedde90a755718","repo":"sgl-project/sglang","slug":"sglang-disagg-staging-buffer-requires-disaggregati","errorCode":null,"errorMessage":"SGLANG_DISAGG_STAGING_BUFFER requires disaggregation_transfer_backend='mooncake' or 'nixl', got '{}'.","messagePattern":"SGLANG_DISAGG_STAGING_BUFFER requires disaggregation_transfer_backend='mooncake' or 'nixl', got '(.+?)'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/arg_groups/pd_disaggregation_hook.py","lineNumber":142,"sourceCode":"                server_args,\n                \"handle_pd_disaggregation\",\n                disaggregation_decode_extra_slots=extra_slots,\n            )\n\n    elif cfg.disaggregation_mode == \"prefill\":\n        assert (\n            cfg.disaggregation_transfer_backend != \"fake\"\n        ), \"Prefill server does not support 'fake' as the transfer backend\"\n\n        if envs.SGLANG_RUST_SERVER.get():\n            _alias_bootstrap_port_to_api_port(server_args)\n\n    if cfg.disaggregation_mode in (\"prefill\", \"decode\"):\n        if (\n            envs.SGLANG_DISAGG_STAGING_BUFFER.get()\n            and cfg.disaggregation_transfer_backend not in (\"mooncake\", \"nixl\")\n        ):\n            raise ValueError(\n                f\"SGLANG_DISAGG_STAGING_BUFFER requires \"\n                f\"disaggregation_transfer_backend='mooncake' or 'nixl', \"\n                f\"got '{cfg.disaggregation_transfer_backend}'.\"\n            )\n\n\ndef _alias_bootstrap_port_to_api_port(server_args: ServerArgs) -> None:\n    \"\"\"Rust-server prefill serves the KV bootstrap registry on the api listener\n    itself, so the resolved bootstrap port must BE the api port — every internal\n    consumer (KVManager registration, PrefillBootstrapQueue) reads the resolved\n    field and agrees automatically. Decode is untouched: there the field names\n    the PREFILL side's bootstrap port and must stay as the operator set it.\n    \"\"\"\n    cfg = resolving_view(server_args)\n    default_port = next(\n        f.default\n        for f in dataclasses.fields(server_args)\n        if f.name == \"disaggregation_bootstrap_port\"","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/arg_groups/pd_disaggregation_hook.py#L124-L160","documentation":"The SGLANG_DISAGG_STAGING_BUFFER env var enables a staging-buffer KV transfer path that only the mooncake and nixl backends implement. Setting it with any other disaggregation transfer backend fails validation in PD modes.","triggerScenarios":"Exporting SGLANG_DISAGG_STAGING_BUFFER=1 (or any truthy value) while --disaggregation-transfer-backend is not mooncake or nixl, in prefill/decode mode.","commonSituations":"Copying performance-tuning env vars from a mooncake-based deployment onto nodes using a different transfer backend; stale env in container images.","solutions":["Unset SGLANG_DISAGG_STAGING_BUFFER","Or switch --disaggregation-transfer-backend to mooncake or nixl"],"exampleFix":"# before\nSGLANG_DISAGG_STAGING_BUFFER=1 --disaggregation-transfer-backend <other>\n# after\nSGLANG_DISAGG_STAGING_BUFFER=1 --disaggregation-transfer-backend mooncake","handlingStrategy":"validation","validationCode":"import os\nif os.environ.get(\"SGLANG_DISAGG_STAGING_BUFFER\") and cfg.disaggregation_transfer_backend not in (\"mooncake\", \"nixl\"):\n    del os.environ[\"SGLANG_DISAGG_STAGING_BUFFER\"]","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Scope performance env vars to the nodes/backends they were tuned for","Clean container env before launch"],"tags":["sglang","pd-disaggregation","staging-buffer","environment-variable","config-validation"],"backgroundTag":"missing-env-var-conflict","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}