{"record":{"id":"9e5ee3a0c2c7ae6f","repo":"sgl-project/sglang","slug":"sglang-disagg-staging-buffer-requires-a-positive-c","errorCode":null,"errorMessage":"SGLANG_DISAGG_STAGING_BUFFER requires a positive chunked_prefill_size that is a multiple of page_size ({page_size}); got {chunked_prefill_size}.","messagePattern":"SGLANG_DISAGG_STAGING_BUFFER requires a positive chunked_prefill_size that is a multiple of page_size \\((.+?)\\); got (.+?)\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/prefill.py","lineNumber":173,"sourceCode":"        self.max_total_num_tokens = (\n            self.scheduler.tp_worker.model_runner.effective_max_total_num_tokens\n        )\n        self.transfer_backend = transfer_backend\n        if envs.SGLANG_DISAGG_STAGING_BUFFER.get():\n            if self.is_mla_backend:\n                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:","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/prefill.py#L155-L191","documentation":"Startup validation for SGLANG_DISAGG_STAGING_BUFFER: the staging mechanism slices each KV send into a fixed page-aligned grid, so chunked_prefill_size must be positive and an exact multiple of the KV pool page_size. -1 (unbounded) or misaligned values have no valid grid and are rejected.","triggerScenarios":"Setting SGLANG_DISAGG_STAGING_BUFFER=1 with --chunked-prefill-size -1, 0, or a value not divisible by the allocator page_size (default fallback 8192 is used when unset only if it divides evenly; any non-multiple trips the check).","commonSituations":"Default chunked_prefill_size (e.g. 8192, 16384) is not a multiple of page_size (e.g. 64) after a model/config change, or an operator explicitly passes -1 for unbounded prefill chunks while enabling the staging buffer.","solutions":["Set --chunked-prefill-size to a positive multiple of page_size, e.g. if page_size=64 use 8192 or 16384.","Check the server log line for the page_size value and align chunked_prefill_size accordingly (or pass --page-size to make alignment easy).","Alternatively unset SGLANG_DISAGG_STAGING_BUFFER to disable staging and keep the current chunk size."],"exampleFix":"# before\nexport SGLANG_DISAGG_STAGING_BUFFER=1\npython -m sglang.launch_server --model qwen --chunked-prefill-size -1 ...\n# after\nexport SGLANG_DISAGG_STAGING_BUFFER=1\npython -m sglang.launch_server --model qwen --chunked-prefill-size 8192 --page-size 64 ...","handlingStrategy":"validation","validationCode":"cps = chunked_prefill_size or 8192\nassert cps > 0 and cps % page_size == 0, (\n    f'chunked_prefill_size={cps} must be a positive multiple of page_size={page_size}')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive chunked_prefill_size programmatically as page_size * N.","Never pass -1 chunked-prefill with staging buffer enabled.","Print page_size at launch and assert alignment in deploy scripts."],"tags":["sglang","disaggregation","chunked-prefill","page-size","config-validation"],"backgroundTag":"invalid-configuration-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}