{"record":{"id":"d707e25309e5dbae","repo":"sgl-project/sglang","slug":"sglang-use-mlx-requires-an-available-pytorch-mps-d","errorCode":null,"errorMessage":"SGLANG_USE_MLX requires an available PyTorch MPS device","messagePattern":"SGLANG_USE_MLX requires an available PyTorch MPS device","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/hardware_backend/mlx/runtime.py","lineNumber":55,"sourceCode":"            \"but MLX is not installed; reinstall with \"\n            \"the srt_mps extra\"\n        ) from None\n    mlx_version = getattr(mx, \"__version__\", None)\n    torch_version = getattr(torch, \"__version__\", None)\n    if not _is_stable_series(\n        torch_version, _SUPPORTED_TORCH_SERIES\n    ) or not _is_stable_at_least(mlx_version, _MIN_MLX_VERSION):\n        raise RuntimeError(\n            \"SGLANG_USE_MLX requires stable Torch 2.13.x and MLX >= 0.32.0; \"\n            \"found \"\n            f\"Torch {torch_version or 'unknown'} + MLX {mlx_version or 'unknown'}; \"\n            \"reinstall with the srt_mps extra\"\n        )\n\n    mps_backend = getattr(torch.backends, \"mps\", None)\n    is_mps_available = getattr(mps_backend, \"is_available\", None)\n    if not callable(is_mps_available) or not is_mps_available():\n        raise RuntimeError(\"SGLANG_USE_MLX requires an available PyTorch MPS device\")\n\n    metal = getattr(mx, \"metal\", None)\n    is_available = getattr(metal, \"is_available\", None)\n    if not callable(is_available) or not is_available():\n        raise RuntimeError(\"SGLANG_USE_MLX requires an available MLX Metal device\")\n\n\n@lru_cache(maxsize=1)\ndef use_mlx() -> bool:\n    \"\"\"Return whether the validated MLX backend was explicitly enabled.\"\"\"\n    enabled = bool(envs.SGLANG_USE_MLX.get())\n    if enabled:\n        _validate_runtime()\n    return enabled\n","sourceCodeStart":37,"sourceCodeEnd":70,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/hardware_backend/mlx/runtime.py#L37-L70","documentation":"The MLX validator requires that PyTorch's MPS (Metal Performance Shaders) backend is present and torch.backends.mps.is_available() returns True after version checks pass. This fires when Torch has no MPS backend attribute, or MPS reports unavailable (no Apple GPU, macOS too old, or a CUDA/Linux build of Torch).","triggerScenarios":"SGLANG_USE_MLX=1 with a CPU/CUDA build of torch (no torch.backends.mps), on a Mac without a supported GPU, on macOS version below MPS requirements, or MPS build available but is_available() returning False.","commonSituations":"Using the default pip torch wheel (CUDA build) on a Mac; running in a Linux container with SGLANG_USE_MLX set; macOS < 12.3 where MPS is unsupported.","solutions":["Install the macOS/MPS build of torch 2.13.x (e.g. pip install torch==2.13.* --force-reinstall, ensuring the arm64 wheel)","Verify torch.backends.mps.is_available() returns True in the target environment","Run on Apple Silicon hardware with a supported macOS version","Unset SGLANG_USE_MLX on non-Apple machines"],"exampleFix":"# before (CUDA/Linux wheel)\npip install torch==2.13.0+cu126\n# after (macOS arm64 wheel)\npip install torch==2.13.0\npython -c \"import torch; assert torch.backends.mps.is_available()\"","handlingStrategy":"validation","validationCode":"def mps_available() -> bool:\n    import torch\n    fn = getattr(getattr(torch.backends, \"mps\", None), \"is_available\", None)\n    return callable(fn) and fn()","typeGuard":null,"tryCatchPattern":"try:\n    use_mlx()\nexcept RuntimeError as e:\n    if \"MPS device\" in str(e):\n        os.environ.pop(\"SGLANG_USE_MLX\", None)  # graceful fallback","preventionTips":["Gate SGLANG_USE_MLX on platform checks (sys.platform == 'darwin' and arm64)","Use the macOS arm64 torch wheel, not the CUDA one","Never set SGLANG_USE_MLX in Linux containers/CI"],"tags":["mlx","mps","torch","apple-silicon","device-unavailable"],"backgroundTag":"device-not-available","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}