{"record":{"id":"4a437a1323a0d528","repo":"sgl-project/sglang","slug":"page-size-mismatch-prefill-server-has-page-size","errorCode":null,"errorMessage":"Page size mismatch: prefill server has page_size={info.page_size}, but decode server has page_size={self.kv_args.page_size}. Both servers must use the same --page-size value.","messagePattern":"Page size mismatch: prefill server has page_size=(.+?), but decode server has page_size=(.+?)\\. Both servers must use the same --page-size value\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/sglang/srt/disaggregation/common/conn.py","lineNumber":626,"sourceCode":"                f\"prefill_dp_rank={-1}&prefill_cp_rank={-1}&\"\n                f\"target_tp_rank={-1}&target_pp_rank={-1}\"\n            )\n            response = requests.get(url, timeout=5)\n            if response.status_code == 200:\n                data = response.json()\n                info = PrefillServerInfo(**data)\n            else:\n                logger.error(\n                    f\"Failed to get prefill server info: {response.status_code}, {response.text}\"\n                )\n                return False\n        except Exception as e:\n            logger.error(f\"Error fetching prefill server info from bootstrap: {e}\")\n            return False\n\n        # Sanity checks\n        if info.page_size is not None and info.page_size != self.kv_args.page_size:\n            raise RuntimeError(\n                f\"Page size mismatch: prefill server has page_size={info.page_size}, \"\n                f\"but decode server has page_size={self.kv_args.page_size}. \"\n                f\"Both servers must use the same --page-size value.\"\n            )\n\n        if (\n            info.kv_cache_dtype is not None\n            and info.kv_cache_dtype != self.kv_cache_dtype_str\n        ):\n            raise RuntimeError(\n                f\"KV cache dtype mismatch: prefill server has kv_cache_dtype={info.kv_cache_dtype}, \"\n                f\"but decode server has kv_cache_dtype={self.kv_cache_dtype_str}. \"\n                f\"Both servers must use the same --kv-cache-dtype value.\"\n            )\n\n        if self.dcp_size > 1:\n            if not (self.is_mla_backend or self.is_hybrid_mla_backend):\n                raise RuntimeError(","sourceCodeStart":608,"sourceCodeEnd":644,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/common/conn.py#L608-L644","documentation":"Raised during PD (prefill-decode) disaggregation startup when the decode server fetches bootstrap info from the prefill server and detects that the --page-size values differ. Page size determines KV cache layout and page-index math on both sides, so a mismatch would corrupt transfer addressing. It is a hard sanity check inside try_ensure_parallel_info.","triggerScenarios":"Decode server calls _ensure_prefill_info -> try_ensure_parallel_info, bootstrap query succeeds, and info.page_size is not None and != self.kv_args.page_size. Happens when the two servers are launched with different --page-size flags.","commonSituations":"Separate launch scripts/helm charts for prefill and decode pools that drifted; copy-paste of server args where one side was tuned (e.g. page_size=1 on decode, 64 on prefill); default value on one side and explicit on the other.","solutions":["Set the same --page-size on both the prefill and decode server launch commands","Check the bootstrap server's reported page_size (logs) against your decode server args and fix the differing side","If using a shared config template, parameterize page_size once and render both launches from it"],"exampleFix":"# before\n# prefill: python -m sglang.launch_server --page-size 64 ...\n# decode:  python -m sglang.launch_server --page-size 1 ...\n# after\n# both:    python -m sglang.launch_server --page-size 64 ...","handlingStrategy":"validation","validationCode":"assert prefill_server_args.page_size == decode_server_args.page_size, 'PD servers must share --page-size'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Render prefill and decode launch commands from one shared config template","Add a deploy-time check that diffs the two servers' ServerArgs"],"tags":["disaggregation","pd-disagg","page-size","config-mismatch","kv-cache"],"backgroundTag":"server-config-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}