{"record":{"id":"7d4c459a344d3c97","repo":"sgl-project/sglang","slug":"sglang-disagg-staging-buffer-with-pp-size-1-is-o","errorCode":null,"errorMessage":"SGLANG_DISAGG_STAGING_BUFFER with pp_size > 1 is only supported by Mooncake.","messagePattern":"SGLANG_DISAGG_STAGING_BUFFER with pp_size > 1 is only supported by Mooncake\\.","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/prefill.py","lineNumber":179,"sourceCode":"                raise RuntimeError(\n                    \"SGLANG_DISAGG_STAGING_BUFFER is designed for non-MLA models \"\n                    \"(e.g. GQA, MHA). MLA models should not set this flag.\"\n                )\n            page_size = self.scheduler.token_to_kv_pool_allocator.page_size\n            # Same source as send_kv_chunk's staging grid below, so validation\n            # and the grid cannot disagree after a post-publish override.\n            chunked_prefill_size = get_schedule().chunked_prefill_size\n            cps = chunked_prefill_size or 8192\n            # Staging slices each send into a fixed page-aligned grid, so an\n            # unbounded (-1) or non-page-aligned chunk size has no valid grid.\n            if cps <= 0 or cps % page_size != 0:\n                raise RuntimeError(\n                    f\"SGLANG_DISAGG_STAGING_BUFFER requires a positive \"\n                    f\"chunked_prefill_size that is a multiple of page_size \"\n                    f\"({page_size}); got {chunked_prefill_size}.\"\n                )\n            if self.pp_size > 1 and self.transfer_backend != TransferBackend.MOONCAKE:\n                raise RuntimeError(\n                    \"SGLANG_DISAGG_STAGING_BUFFER with pp_size > 1 is only \"\n                    \"supported by Mooncake.\"\n                )\n            if get_parallel().enable_prefill_context_parallel:\n                # CP rewrites index_slice per rank, breaking the chunk grid.\n                raise RuntimeError(\n                    \"SGLANG_DISAGG_STAGING_BUFFER does not support \"\n                    \"prefill context parallelism.\"\n                )\n        self.kv_manager = self._init_kv_manager()\n\n    def _init_kv_manager(self) -> CommonKVManager:\n        kv_args_class = get_kv_class(self.transfer_backend, KVClassType.KVARGS)\n        kv_args = kv_args_class()\n        kv_args.engine_rank = self.tp_rank\n        kv_args.pp_rank = self.pp_rank\n        kv_args.system_dp_rank = self.scheduler.ps.dp_rank\n        kv_args.kv_cache_dtype_str = (","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/prefill.py#L161-L197","documentation":"With SGLANG_DISAGG_STAGING_BUFFER enabled and pipeline parallelism (pp_size > 1), only the Mooncake transfer backend implements the staging buffer correctly across pipeline stages; NIXL is rejected at startup.","triggerScenarios":"SGLANG_DISAGG_STAGING_BUFFER=1 plus --pipeline-parallel-size > 1 while --disaggregation-transfer-backend nixl (or any non-mooncake backend) is configured.","commonSituations":"Scaling up a PD deployment to multi-stage pipeline parallelism and keeping NIXL as transfer backend with the staging optimization still exported in the launch script.","solutions":["Switch to --disaggregation-transfer-backend mooncake when pp_size > 1 with staging buffer.","Or reduce --pipeline-parallel-size to 1.","Or unset SGLANG_DISAGG_STAGING_BUFFER to keep NIXL with PP."],"exampleFix":"# before\nexport SGLANG_DISAGG_STAGING_BUFFER=1\npython -m sglang.launch_server --disaggregation-transfer-backend nixl --pipeline-parallel-size 2 ...\n# after\nexport SGLANG_DISAGG_STAGING_BUFFER=1\npython -m sglang.launch_server --disaggregation-transfer-backend mooncake --pipeline-parallel-size 2 ...","handlingStrategy":"validation","validationCode":"if envs.SGLANG_DISAGG_STAGING_BUFFER.get() and pp_size > 1:\n    assert transfer_backend == TransferBackend.MOONCAKE, 'staging buffer + PP requires mooncake'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Encode backend-PP compatibility rules in deployment templates.","Re-validate transfer backend choice whenever PP degree changes."],"tags":["sglang","disaggregation","pipeline-parallelism","mooncake","nixl","config-validation"],"backgroundTag":"unsupported-feature-configuration","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}