{"record":{"id":"fe2cd1fe140135f7","repo":"sgl-project/sglang","slug":"nccl-only-supports-cuda-rocm-and-musa-backends-fe2cd1","errorCode":null,"errorMessage":"NCCL only supports CUDA, ROCm and MUSA backends.","messagePattern":"NCCL only supports CUDA, ROCm and MUSA backends\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/distributed/device_communicators/pynccl_wrapper.py","lineNumber":63,"sourceCode":"    \"\"\"\n\n    # so_file can be set to None in sglang\n    so_file = os.environ.get(\"SGLANG_NCCL_SO_PATH\", None)\n\n    # manually load the nccl library\n    if so_file:\n        logger.info(\n            \"Found nccl from environment variable SGLANG_NCCL_SO_PATH=%s\", so_file\n        )\n    else:\n        if torch.version.cuda is not None:\n            so_file = \"libnccl.so.2\"\n        elif torch.version.hip is not None:\n            so_file = \"librccl.so.1\"\n        elif hasattr(torch.version, \"musa\") and torch.version.musa is not None:\n            so_file = \"libmccl.so.2\"\n        else:\n            raise ValueError(\"NCCL only supports CUDA, ROCm and MUSA backends.\")\n        logger.debug(\"Found nccl from library %s\", so_file)\n    return so_file\n\n\n# === export types and functions from nccl to Python ===\n# for the original nccl definition, please check\n# https://github.com/NVIDIA/nccl/blob/master/src/nccl.h.in\n\nncclResult_t = ctypes.c_int\nncclComm_t = ctypes.c_void_p\nncclWindow_t = ctypes.c_void_p\n\n\n# Sentinels NCCL uses to mark \"use the default value\", see\n# NCCL_CONFIG_UNDEF_INT / NCCL_CONFIG_UNDEF_PTR / NCCL_API_MAGIC in nccl.h.in.\nNCCL_CONFIG_UNDEF_INT = -(2**31)  # INT_MIN\nNCCL_CONFIG_UNDEF_PTR = None\nNCCL_API_MAGIC = 0xCAFEBEEF","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/distributed/device_communicators/pynccl_wrapper.py#L45-L81","documentation":"PyNcclWrapper needs to locate the NCCL shared library (libnccl.so.2 on CUDA, librccl.so.1 on ROCm/HIP, libmccl.so.2 on MUSA) before loading it via ctypes. find_nccl_library picks the file based on torch.version.cuda/hip/musa; if none is set, PyTorch was built for a different backend and the wrapper refuses with ValueError.","triggerScenarios":"Constructing PyNcclWrapper (custom allreduce / pynccl path) in a PyTorch build where torch.version.cuda, torch.version.hip, and torch.version.musa are all None — e.g. CPU-only or other-accelerator torch builds — so no NCCL library can be selected.","commonSituations":"Running sglang distributed init with a CPU-only torch wheel (often accidentally installed when CUDA torch was intended); a torch build for an unsupported accelerator; importing distributed utilities in unit tests on a CPU CI machine.","solutions":["Install a CUDA (or ROCm/MUSA) build of PyTorch matching your system, e.g. pip install torch --index-url https://download.pytorch.org/whl/cu121","Verify the backend: python -c 'import torch; print(torch.version.cuda, torch.version.hip)' — one must be non-None","Ensure the corresponding NCCL library (libnccl.so.2 / librccl.so.1) is installed and on LD_LIBRARY_PATH","If CPU-only execution is intended, avoid the pynccl/custom-parallel code paths"],"exampleFix":"# before\npip list | grep torch  # torch (CPU-only build) -> ValueError\n\n# after\npip uninstall torch\npip install torch --index-url https://download.pytorch.org/whl/cu121","handlingStrategy":"type-guard","validationCode":"import torch\nbackend = torch.version.cuda or torch.version.hip or getattr(torch.version, 'musa', None)\nif backend is None:\n    raise RuntimeError('Need CUDA/ROCm/MUSA torch build for PyNcclWrapper')","typeGuard":"def has_gpu_backend() -> bool:\n    import torch\n    return (torch.version.cuda is not None\n            or torch.version.hip is not None\n            or getattr(torch.version, 'musa', None) is not None)","tryCatchPattern":"try:\n    wrapper = PyNcclWrapper(...)\nexcept ValueError as e:\n    if 'only supports CUDA, ROCm and MUSA' in str(e):\n        # skip pynccl custom allreduce, use torch.distributed defaults\n        ...\n    raise","preventionTips":["Install GPU-specific torch wheels explicitly via --index-url","Assert torch.cuda.is_available() in distributed launch scripts","Keep CPU environments off pynccl code paths (guard with capability checks)"],"tags":["nccl","pytorch","cuda","backend-not-supported","distributed","sglang"],"backgroundTag":"unsupported-hardware-backend","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}