{"record":{"id":"bfdc302809cd7919","repo":"sgl-project/sglang","slug":"cuda-vmm-proxy-has-no-shareable-handle","errorCode":null,"errorMessage":"CUDA VMM proxy has no shareable handle","messagePattern":"CUDA VMM proxy has no shareable handle","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/utils/cuda_vmm_transport_utils.py","lineNumber":667,"sourceCode":"            ]\n        )\n\n\n_imported_pool_cache: dict[tuple, _ImportedCudaVmmPool] = {}\n_imported_pool_cache_lock = threading.Lock()\n\n\ndef _get_imported_pool(\n    *,\n    fabric_handle: bytes | None,\n    posix_socket_path: str | None,\n    allocation_size: int,\n    device_index: int,\n) -> _ImportedCudaVmmPool:\n    use_fabric = fabric_handle is not None\n    transport_handle = fabric_handle if use_fabric else posix_socket_path\n    if transport_handle is None:\n        raise RuntimeError(\"CUDA VMM proxy has no shareable handle\")\n    key = (device_index, allocation_size, transport_handle)\n    pool = _imported_pool_cache.get(key)\n    if pool is not None:\n        return pool\n\n    with _imported_pool_cache_lock:\n        pool = _imported_pool_cache.get(key)\n        if pool is not None:\n            return pool\n\n        fd = None\n        try:\n            if not use_fabric:\n                fd = _receive_posix_fd(posix_socket_path)\n            with torch.cuda.device(device_index):\n                pointer = import_and_map_alloc(\n                    fabric_handle,\n                    fd,","sourceCodeStart":649,"sourceCodeEnd":685,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/utils/cuda_vmm_transport_utils.py#L649-L685","documentation":"Raised when building/importing a CUDA VMM pool on the consumer side and neither a fabric handle nor a POSIX socket path handle was provided. The proxy needs at least one OS-level shareable handle to import the exporter's virtual memory allocation; with none, import is impossible.","triggerScenarios":"Calling _get_imported_pool / _pool with fabric_handle=None and posix_socket_path=None; handle fields dropped during IPC serialization; running on a platform where fabric handle creation failed and the socket path was not set as fallback.","commonSituations":"Misconfigured multi-process setup where the exporter didn't create a shareable handle; gateway/NVSwitch-less machines where fabric handles are unavailable and the POSIX path fallback wasn't configured; serialization bug dropping handle attributes.","solutions":["Verify the exporter side creates either a fabric or POSIX-socket handle for the allocation","Check the transport config/launch flags enable the handle mechanism appropriate for the fabric topology (POSIX for single host, fabric for multi-node)","Inspect the IPC message carrying the handles to confirm fields are populated before constructing the proxy"],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"if fabric_handle is None and posix_socket_path is None:\n    raise ValueError(\"cannot import VMM pool: no shareable handle provided\")","typeGuard":"def has_shareable_handle(proxy_msg) -> bool:\n    return proxy_msg.fabric_handle is not None or proxy_msg.posix_socket_path is not None","tryCatchPattern":null,"preventionTips":["Always export at least one handle type on the producer side","Validate IPC payloads carry non-None handles before constructing proxies"],"tags":["cuda","vmm","ipc","handle","multiprocessing"],"backgroundTag":"missing-shared-memory-handle","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}