{"record":{"id":"6bb0911fbc46acca","repo":"sgl-project/sglang","slug":"cannot-find-nvidia-math-dx-cublasdx-headers-ins","errorCode":null,"errorMessage":"Cannot find NVIDIA Math-DX (cuBLASDx) headers. Install the `nvidia-mathdx` package (`pip install nvidia-mathdx`) or set MATHDX_HOME to an extracted Math-DX archive root.","messagePattern":"Cannot find NVIDIA Math-DX \\(cuBLASDx\\) headers\\. Install the `nvidia-mathdx` package \\(`pip install nvidia-mathdx`\\) or set MATHDX_HOME to an extracted Math-DX archive root\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/jit/utils/deps.py","lineNumber":94,"sourceCode":"    # handles regular packages.\n    spec = importlib.util.find_spec(\"nvidia.mathdx\")\n    if spec is not None:\n        roots = list(spec.submodule_search_locations or [])\n        if spec.origin is not None:\n            roots.append(str(pathlib.Path(spec.origin).parent))\n        for root in roots:\n            candidate = pathlib.Path(root).resolve()\n            if (candidate / \"include\").exists():\n                return candidate\n\n    return None\n\n\n@register_dependency(\"mathdx\")\ndef get_mathdx_include_paths() -> List[str]:\n    root = get_mathdx_root()\n    if root is None:\n        raise RuntimeError(\n            \"Cannot find NVIDIA Math-DX (cuBLASDx) headers. \"\n            \"Install the `nvidia-mathdx` package \"\n            \"(`pip install nvidia-mathdx`) or set MATHDX_HOME to an \"\n            \"extracted Math-DX archive root.\"\n        )\n    candidates = [root / \"include\"]\n    cutlass = root / \"external\" / \"cutlass\" / \"include\"\n    if cutlass.exists():\n        candidates.append(cutlass)\n    return [str(p) for p in candidates]\n\n\n@register_dependency(\"cutlass\")\ndef get_cutlass_include_paths() -> List[str]:\n    include_paths: List[str] = []\n\n    flashinfer_root = _find_package_root(\"flashinfer\")\n    if flashinfer_root is not None:","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/jit/utils/deps.py#L76-L112","documentation":"The SGLang JIT kernel build system cannot locate NVIDIA Math-DX (cuBLASDx) headers, which are required to compile JIT kernels that use cuBLASDx. The resolver first checks the MATHDX_HOME environment variable, then looks for an installed nvidia-mathdx pip package or extracted archive; when none is found it raises this RuntimeError from get_mathdx_include_paths().","triggerScenarios":"Building/compiling a JIT kernel registered with the @register_dependency(\"mathdx\") decorator (any kernel whose CMake/source list calls get_mathdx_include_paths()) on a machine without the nvidia-mathdx wheel installed and without MATHDX_HOME pointing at an extracted Math-DX archive root.","commonSituations":"Fresh CI runner or Docker image that installs sglang but not the optional nvidia-mathdx dependency; GPU driver/CUDA stack upgraded and a previously working MATHDX_HOME path no longer exists; using a CUDA version for which the nvidia-mathdx wheel was not installed via pip index.","solutions":["pip install nvidia-mathdx (matches your installed CUDA major version)","Set MATHDX_HOME to the root of an extracted Math-DX archive (a directory containing include/), e.g. export MATHDX_HOME=/opt/mathdx","If behind a firewall, download the Math-DX archive from NVIDIA, extract it, and point MATHDX_HOME at it","Verify by running python -c 'from sglang.kernels.jit.utils.deps import get_mathdx_root; print(get_mathdx_root())' and ensure it returns a path containing include/cublasdx"],"exampleFix":"# before: MATHDX_HOME unset, nvidia-mathdx not installed -> RuntimeError\npip install nvidia-mathdx\n# after\nexport MATHDX_HOME=/opt/nvidia/mathdx  # or rely on the pip package\npython -c \"from sglang.kernels.jit.utils.deps import get_mathdx_include_paths; print(get_mathdx_include_paths())\"","handlingStrategy":"validation","validationCode":"import os\nfrom sglang.kernels.jit.utils.deps import get_mathdx_root\nif get_mathdx_root() is None and not os.environ.get('MATHDX_HOME'):\n    raise SystemExit('Install nvidia-mathdx or set MATHDX_HOME before building JIT kernels')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin nvidia-mathdx in the environment alongside the matching CUDA version","Set MATHDX_HOME in Dockerfile/CI env so kernel builds never depend on wheel layout","Add an env-check smoke test that calls get_mathdx_root() before the first JIT build"],"tags":["cuda","jit-kernel","missing-dependency","nvidia","build"],"backgroundTag":"missing-optional-dependency","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}