{"record":{"id":"6098b8d7f37709b4","repo":"sgl-project/sglang","slug":"unsupported-io-backend-io-backend-6098b8","errorCode":null,"errorMessage":"Unsupported IO backend: {io_backend}","messagePattern":"Unsupported IO backend: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/pool_host/mha.py","lineNumber":370,"sourceCode":"                raise ValueError(f\"Unsupported layout: {self.layout}\")\n        elif io_backend == \"kernel_ascend\":\n            if self.layout == \"page_first_direct\":\n                # Ascend-specific: transfer KV data for all layers when layer_id == 0\n                if host_layer_id == 0:\n                    transfer_kv_dim_exchange(\n                        device_indices=device_indices,\n                        host_indices=host_indices,\n                        device_k=device_pool.k_buffer,\n                        host_k=self.k_buffer,\n                        device_v=device_pool.v_buffer,\n                        host_v=self.v_buffer,\n                        page_size=self.page_size,\n                        direction=TransferDirection.H2D,\n                    )\n            else:\n                raise ValueError(f\"Unsupported layout: {self.layout}\")\n        else:\n            raise ValueError(f\"Unsupported IO backend: {io_backend}\")\n\n    def _resolve_device_transfer_buffers(self, device_pool):\n        if self.mtp_draft_device_pools:\n            return (\n                self.packed_device_k_data_ptrs,\n                self.packed_device_v_data_ptrs,\n                self.packed_device_k_buffers,\n                self.packed_device_v_buffers,\n            )\n        return (\n            device_pool.k_data_ptrs,\n            device_pool.v_data_ptrs,\n            device_pool.k_buffer,\n            device_pool.v_buffer,\n        )\n\n    def backup_from_device_all_layer(\n        self, device_pool, host_indices, device_indices, io_backend","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/pool_host/mha.py#L352-L388","documentation":"Terminal dispatch guard in load_to_device_per_layer: the MHA host pool implements H2D restore only for specific io_backends ('kernel'-family, 'direct', 'kernel_ascend'). Any other backend string (or a typo) has no transfer implementation and the method refuses to proceed.","triggerScenarios":"Calling load_to_device_per_layer with io_backend not in the handled set — e.g. 'cuda', 'nvshmem', an empty string, or a custom backend name not wired into this method.","commonSituations":"Setting --io-backend to an unsupported or misspelled value while hierarchical cache is enabled; new platforms whose backend name isn't registered here; forks adding an io_backend without implementing H2D transfer.","solutions":["Set io_backend to one of the supported values for hierarchical cache ('kernel', 'direct', 'kernel_ascend' as appropriate for your device)","Disable hierarchical cache if you don't need offload, avoiding this code path entirely","If adding a new backend, implement its branch in load_to_device_per_layer (and backup_from_device_all_layer)","Check SGLang version docs for the current list of supported io_backend values"],"exampleFix":"# before\nserver_args.io_backend = \"cuda\"  # unsupported\n# after\nserver_args.io_backend = \"kernel\"","handlingStrategy":"validation","validationCode":"SUPPORTED_IO_BACKENDS = {\"kernel\", \"direct\", \"kernel_ascend\"}\nassert server_args.io_backend in SUPPORTED_IO_BACKENDS, server_args.io_backend","typeGuard":"def is_supported_io_backend(b: str) -> bool:\n    return b in {\"kernel\", \"direct\", \"kernel_ascend\"}","tryCatchPattern":"try:\n    host_pool.load_to_device_per_layer(...)\nexcept ValueError as e:\n    if \"IO backend\" in str(e):\n        logger.error(\"Bad io_backend for hierarchical cache: %s\", io_backend)\n        raise","preventionTips":["Validate io_backend against the documented set at launch-script startup","Avoid fabricating backend names for custom hardware without implementing the transfer paths"],"tags":["sglang","io-backend","kv-cache","hierarchical-cache","configuration"],"backgroundTag":"unsupported-backend-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}