sgl-project/sglang · error · ValueError

Insufficient destination DCP pages: required={required_pages

Error message

Insufficient destination DCP pages: required={required_pages}, provided={dst_pages.size}, src_page_offset={src_page_offset}, dcp_rank={dcp_rank}

What it means

After mapping destination token positions to page ordinals (dst_page_ordinals), the plan validates that the provided dst_pages list is long enough: the max ordinal must be < dst_pages.size. If not, it raises with required_pages and the dcp_rank/src_page_offset for debugging. This means the decode-side DCP allocation is too small for the tokens to be placed.

Source

Thrown at python/sglang/srt/disaggregation/common/utils.py:193

    chunk_start = decode_prefix_len + src_page_offset * physical_page_size
    first_owned_offset = (dcp_rank - chunk_start) % dcp_size
    owned_offsets = np.arange(
        first_owned_offset, num_kv_tokens, dcp_size, dtype=np.int64
    )
    src_token_indices = (
        src_pages[owned_offsets // physical_page_size] * physical_page_size
        + owned_offsets % physical_page_size
    )

    relative_positions = src_page_offset * physical_page_size + owned_offsets
    dst_local_offsets = relative_positions // dcp_size
    dst_page_ordinals = dst_local_offsets // physical_page_size
    if dst_page_ordinals.size and (
        dst_pages.size == 0 or int(dst_page_ordinals.max()) >= dst_pages.size
    ):
        required_pages = int(dst_page_ordinals.max()) + 1
        raise ValueError(
            "Insufficient destination DCP pages: "
            f"required={required_pages}, provided={dst_pages.size}, "
            f"src_page_offset={src_page_offset}, dcp_rank={dcp_rank}"
        )

    dst_token_indices = (
        dst_pages[dst_page_ordinals] * physical_page_size
        + dst_local_offsets % physical_page_size
    )
    return DCPTokenTransferPlan(src_token_indices, dst_token_indices)

View on GitHub (pinned to 0132848349)

Solutions

1. Allocate more destination pages on decode for the request (check allocator accounting vs transfer span)
2. Verify src_page_offset matches which slice of the virtual pages this dcp_rank owns
3. Log dst_page_ordinals.max(), dst_pages.size and dcp_rank at the call site to see the shortfall

required = (dst_local_offsets.max() // physical_page_size) + 1 if dst_local_offsets.size else 0
assert dst_pages.size >= required, (required, dst_pages.size)

When it happens

Trigger: send_kvcache_dcp where the destination page list for a DCP rank covers fewer pages than the transferred token span requires — e.g. decode allocated only part of the virtual-page span or a mis-set src_page_offset shifted positions.

Common situations: Decode allocator returning a short page run for the request; src_page_offset not accounting for prior DCP ranks' shares; prefix alignment issues inflating dst_local_offsets.

Related errors

• PD peers must connect matching DCP ranks, got prefill={self.
• Unsupported PD DCP topology: {self.dcp_size} -> {dst_dcp_siz
• PD DCP source/destination KV geometry differs: src={src_toke
• PD decode DCP requires an MLA or hybrid-MLA KV pool.
• PD decode DCP currently requires prefill attention CP=1, got

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