sgl-project/sglang · error · ValueError

Layer-sharded direct DSA indexer backup only supports layer_

Error message

Layer-sharded direct DSA indexer backup only supports layer_first layout, got {self.layout}

What it means

In the 'direct' IO backend branch of _backup_from_device_per_layer, only layer_first layout is implemented for layer-sharded backups, so page_first (or any other layout) is rejected with this message.

Source

Thrown at python/sglang/srt/mem_cache/pool_host/dsa.py:328

                )
            elif self.layout == "page_first":
                raise ValueError(
                    "Layer-sharded DSA indexer HiCache backup with page_first "
                    "layout is not supported without a per-layer LF->PF kernel."
                )
            else:
                raise ValueError(f"Unsupported layout: {self.layout}")
        elif io_backend == "direct":
            if self.layout == "layer_first":
                transfer_kv_direct(
                    src_layers=[device_pool.index_k_with_scale_buffer[device_layer_id]],
                    dst_layers=[self.index_k_with_scale_buffer[host_layer_id]],
                    src_indices=device_page_indices,
                    dst_indices=host_page_indices,
                    page_size=1,
                )
            else:
                raise ValueError(
                    "Layer-sharded direct DSA indexer backup only supports "
                    f"layer_first layout, got {self.layout}"
                )
        else:
            raise ValueError(f"Unsupported IO backend: {io_backend}")

    def backup_from_device_all_layer(
        self, device_pool, host_indices, device_indices, io_backend
    ):
        if self._is_device_layer_sharded(device_pool):
            for layer_id in self._owned_device_layer_ids(device_pool):
                self._backup_from_device_per_layer(
                    device_pool, host_indices, device_indices, layer_id, io_backend
                )
            for draft_layer_id, draft_device_pool in enumerate(
                self.mtp_draft_device_pools
            ):
                self._backup_from_device_per_layer(

View on GitHub (pinned to 0132848349)

Solutions

1. Use layout='layer_first' with the direct backend
2. Or use the kernel backend with layer_first (page_first is unsupported for sharded backup there too)

Example fix

# before
layout='page_first'; io_backend='direct'
# after
layout='layer_first'; io_backend='direct'

if io_backend == "direct" and layer_sharded:
    assert layout == "layer_first"

def direct_sharded_backup_supported(layout: str) -> bool:
    return layout == "layer_first"

When it happens

Trigger: backup_from_device_all_layer with io_backend='direct', a layer-sharded device pool, and layout='page_first'.

Common situations: Combining direct IO backend with page_first host layout while device pool is layer sharded.

Related errors

• Unsupported V4 paged host layout/backend: {self.layout}/{io_
• Unsupported layout: {self.layout}
• Unsupported IO backend: {io_backend}
• Layer-sharded DSA indexer HiCache backup with page_first lay
• Unsupported layout for models with head_dim != v_head_dim an

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