sgl-project/sglang · error · NotImplementedError

DSV4 HiSparse direct PD transfer currently requires the Moon

Error message

DSV4 HiSparse direct PD transfer currently requires the Mooncake backend

What it means

While popping preallocated requests, the DSV4 (DeepSeek-V4) HiSparse direct PD transfer path builds device_kv_indices and only supports the Mooncake transfer backend; any other backend raises NotImplementedError. HiSparse requires Mooncake's device-side transfer API to move KV directly without host staging.

Source

Thrown at python/sglang/srt/disaggregation/decode.py:1492

            if (
                self.scheduler.enable_hisparse
                and isinstance(self.token_to_kv_pool, DeepSeekV4TokenToKVPool)
                and not _is_fake_transfer(decode_req.req)
            ):
                # alloc_logical_only() already allocated the shared logical pages
                # used by C4 indexer and C128 KV. These device buffers do not use
                # the C4 sparse physical-slot mapping; carry their logical page IDs
                # alongside the independently allocated C4 host page IDs.
                full_kv_indices = self.req_to_token_pool.req_to_token[
                    decode_req.req.req_pool_idx,
                    prefix_len:origin_input_len,
                ]
                device_page_indices = kv_to_page_indices(
                    full_kv_indices,
                    page_size,
                ).astype(np.int32)
                if self.transfer_backend != TransferBackend.MOONCAKE:
                    raise NotImplementedError(
                        "DSV4 HiSparse direct PD transfer currently requires "
                        "the Mooncake backend"
                    )
            metadata_kwargs = {"decode_prefix_len": total_prefix_len}
            if device_page_indices is not None:
                metadata_kwargs["device_kv_indices"] = device_page_indices
            if (
                self.transfer_queue.enable_staging
                and hasattr(decode_req.kv_receiver, "require_staging")
                and decode_req.kv_receiver.require_staging
            ):
                # Register before send_metadata, which triggers the STAGING_REQ
                # prefetch (dropped for an unregistered room); tiny race, correct order.
                self.transfer_queue.staging_handler.register_decode_req(
                    decode_req.req.bootstrap_room, decode_req
                )
            decode_req.kv_receiver.send_metadata(
                page_indices,

View on GitHub (pinned to 0132848349)

Solutions

1. Set --disaggregation-transfer-backend mooncake for DSV4 HiSparse PD deployments
2. Ensure a compatible Mooncake version with device transfer support is installed (sgl-kernel/mooncake packages)
3. If Mooncake is unavailable in your environment, disable the HiSparse direct path or use a supported model until support lands

Example fix

# before
--disaggregation-transfer-backend nixl  # DSV4 HiSparse
# after
--disaggregation-transfer-backend mooncake

if is_dsv4_hisparse(model_path):
    assert transfer_backend == TransferBackend.MOONCAKE, 'HiSparse PD requires mooncake'

def hisparse_pd_supported(backend: str, model: str) -> bool:
    return 'dsv4' not in model.lower() or backend == 'mooncake'

When it happens

Trigger: Running a DSV4/HiSparse model in PD disaggregation with --disaggregation-transfer-backend set to something other than mooncake (e.g. nixl or fake) while the direct transfer path is taken in pop_preallocated.

Common situations: Reusing an existing NIXL-based PD deployment config for a new HiSparse model; defaulting to a non-Mooncake backend and upgrading to a DSV4 model.

Related errors

• mooncake encoder_transfer_backend requires HTTP encoders; us
• No embedding available for Mooncake GPU-direct transfer: {re
• Rank 0 produced no embedding for {ctx.req_id}
• SGLANG_DISAGG_STAGING_BUFFER with pp_size > 1 is only suppor
• HiSparse speculative swap requires 2-4 steps, got {num_steps

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