sgl-project/sglang · critical · RuntimeError

Page size mismatch: prefill server has page_size={info.page_

Error message

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.

What it means

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.

Source

Thrown at python/sglang/srt/disaggregation/common/conn.py:626

                f"prefill_dp_rank={-1}&prefill_cp_rank={-1}&"
                f"target_tp_rank={-1}&target_pp_rank={-1}"
            )
            response = requests.get(url, timeout=5)
            if response.status_code == 200:
                data = response.json()
                info = PrefillServerInfo(**data)
            else:
                logger.error(
                    f"Failed to get prefill server info: {response.status_code}, {response.text}"
                )
                return False
        except Exception as e:
            logger.error(f"Error fetching prefill server info from bootstrap: {e}")
            return False

        # Sanity checks
        if info.page_size is not None and info.page_size != self.kv_args.page_size:
            raise RuntimeError(
                f"Page size mismatch: prefill server has page_size={info.page_size}, "
                f"but decode server has page_size={self.kv_args.page_size}. "
                f"Both servers must use the same --page-size value."
            )

        if (
            info.kv_cache_dtype is not None
            and info.kv_cache_dtype != self.kv_cache_dtype_str
        ):
            raise RuntimeError(
                f"KV cache dtype mismatch: prefill server has kv_cache_dtype={info.kv_cache_dtype}, "
                f"but decode server has kv_cache_dtype={self.kv_cache_dtype_str}. "
                f"Both servers must use the same --kv-cache-dtype value."
            )

        if self.dcp_size > 1:
            if not (self.is_mla_backend or self.is_hybrid_mla_backend):
                raise RuntimeError(

View on GitHub (pinned to 0132848349)

Solutions

1. Set the same --page-size on both the prefill and decode server launch commands
2. Check the bootstrap server's reported page_size (logs) against your decode server args and fix the differing side
3. If using a shared config template, parameterize page_size once and render both launches from it

Example fix

# before
# prefill: python -m sglang.launch_server --page-size 64 ...
# decode:  python -m sglang.launch_server --page-size 1 ...
# after
# both:    python -m sglang.launch_server --page-size 64 ...

assert prefill_server_args.page_size == decode_server_args.page_size, 'PD servers must share --page-size'

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• KV cache dtype mismatch: prefill server has kv_cache_dtype={
• kv-canary: RealKvSource.page_size must be >= 1, got {self.pa
• PD DCP source/destination KV geometry differs: src={src_toke
• PD decode DCP currently requires prefill attention CP=1, got
• PD KV layout mismatch on the whole-envelope path: prefill ha

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/4a437a1323a0d528. Report an issue: GitHub.