{"record":{"id":"ed41382b8d3a7484","repo":"sgl-project/sglang","slug":"unsupported-io-backend-for-models-with-head-dim","errorCode":null,"errorMessage":"Unsupported IO backend for models with head_dim != v_head_dim: {io_backend}; expected 'kernel' or 'direct'.","messagePattern":"Unsupported IO backend for models with head_dim != v_head_dim: (.+?); expected 'kernel' or 'direct'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/pool_host/mha.py","lineNumber":1216,"sourceCode":"                )\n            transfer_kv_per_layer_direct_pf_lf(\n                src_ptrs=[self.k_buffer],\n                dst_ptrs=[device_pool.k_buffer[device_layer_id]],\n                src_indices=host_indices,\n                dst_indices=device_indices,\n                layer_id=host_layer_id,\n                page_size=self.page_size,\n            )\n            transfer_kv_per_layer_direct_pf_lf(\n                src_ptrs=[self.v_buffer],\n                dst_ptrs=[device_pool.v_buffer[device_layer_id]],\n                src_indices=host_indices,\n                dst_indices=device_indices,\n                layer_id=host_layer_id,\n                page_size=self.page_size,\n            )\n        else:\n            raise ValueError(\n                f\"Unsupported IO backend for models with head_dim != v_head_dim: \"\n                f\"{io_backend}; expected 'kernel' or 'direct'.\"\n            )\n\n    def backup_from_device_all_layer(\n        self, device_pool, host_indices, device_indices, io_backend\n    ):\n        (\n            device_k_data_ptrs,\n            device_v_data_ptrs,\n            device_k_buffers,\n            device_v_buffers,\n        ) = self._resolve_device_transfer_buffers(device_pool)\n        if io_backend == \"kernel\":\n            if self.layout != \"page_first\":\n                raise ValueError(\n                    f\"Unsupported layout for models with head_dim != v_head_dim \"\n                    f\"and io_backend='kernel': {self.layout}; expected 'page_first'.\"","sourceCodeStart":1198,"sourceCodeEnd":1234,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/pool_host/mha.py#L1198-L1234","documentation":"load_to_device_per_layer for head_dim != v_head_dim models only implements the 'kernel' and 'direct' IO backends; any other io_backend string reaches this guard.","triggerScenarios":"Calling load_to_device_per_layer(..., io_backend=...) with a value like 'cuda', 'memcpy', or None on the asymmetric-head-dim MLA pool.","commonSituations":"Passing an io_backend resolved from stale config or custom code; typos; backend names removed in newer SGLang.","solutions":["Pass 'kernel' or 'direct'","Source io_backend from server_args.hicache_io_backend instead of literals","Upgrade custom fork code that used removed backend identifiers"],"exampleFix":"# before\npool.load_to_device_per_layer(dev, ..., io_backend=\"memcpy\")\n# after\npool.load_to_device_per_layer(dev, ..., io_backend=\"kernel\")","handlingStrategy":"validation","validationCode":"assert io_backend in (\"kernel\", \"direct\"), f\"unsupported io_backend {io_backend!r}\"","typeGuard":"def is_valid_io_backend(b: str) -> bool:\n    return b in (\"kernel\", \"direct\")","tryCatchPattern":"try:\n    pool.load_to_device_per_layer(...)\nexcept ValueError as e:\n    if \"Unsupported IO backend\" in str(e):\n        pool.load_to_device_per_layer(..., io_backend=\"kernel\")\n    else:\n        raise","preventionTips":["Use server_args.hicache_io_backend as the source of truth","Validate backend strings at config parse time"],"tags":["sglang","mla","hicache","io-backend"],"backgroundTag":"invalid-backend-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}