sgl-project/sglang · error · ValueError

Insufficient destination DCP pages: required=

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.

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

• num_kv_tokens must fit in the provided source pages, got…
• PD DCP source/destination KV geometry differs: src=
• PD DCP transfer requires decode_prefix_len to align to the…
• PD decode DCP currently requires prefill attention CP=1, got
• PD decode DCP requires an MLA or hybrid-MLA KV pool.

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

Appendix: 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)