sgl-project/sglang · error · RuntimeError

Unknown weight cache transport backend

Error message

Unknown weight cache transport backend {name!r}

What it means

Weight-cache transport factory error: an unknown backend name (shown in the message) was requested. Choose a registered backend (e.g. the POSIX-FD / shared-memory transports) spelled exactly as registered.

Solutions

1. Use 'torch_ipc' (default) or 'vmm_fd'
2. Check spelling/case of the backend name in your launch config

Example fix

# before
get_client_transport_backend("torch-ipc")
# after
get_client_transport_backend("torch_ipc")

from sglang.srt.weight_cache.transport import TORCH_IPC_BACKEND, VMM_FD_BACKEND
if name not in (None, '', TORCH_IPC_BACKEND, VMM_FD_BACKEND):
    name = None

def is_valid_backend(name):
    return name in (None, '', 'torch_ipc', 'vmm_fd')

When it happens

Trigger: Passing a typo'd backend string (e.g. 'torch-ipc', 'VMM_FD') via CLI flag or env var to the IpcModelLoader constructor or _fetch_from_cache.

Common situations: Typo in --weight-cache-transport-backend; config written for a different sglang version with renamed backends.

Related errors

• Invalid quantization method
• weight cache transport backend
• A CUDA VMM-enabled model must provide a multimodal processor
• Activation function is not supported.
• allowed media domains cannot be empty

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

Appendix: source

Thrown at python/sglang/srt/weight_cache/transport.py:205

        self._raise_not_implemented()


def choose_daemon_transport_backend(
    state_tensors: Mapping[str, Tuple[torch.Tensor, bool]],
) -> WeightCacheTransportBackend:
    if VmmFdTransportBackend.can_export_state(state_tensors):
        logger.info("[weight_cache] Using transport backend: %s", VMM_FD_BACKEND)
        return VmmFdTransportBackend()
    logger.info("[weight_cache] Using transport backend: %s", TORCH_IPC_BACKEND)
    return TorchIpcTransportBackend()


def get_client_transport_backend(name: Optional[str]) -> WeightCacheTransportBackend:
    if name in (None, "", TORCH_IPC_BACKEND):
        return TorchIpcTransportBackend()
    if name == VMM_FD_BACKEND:
        return VmmFdTransportBackend()
    raise RuntimeError(f"Unknown weight cache transport backend {name!r}")

View on GitHub (pinned to 0132848349)