{"record":{"id":"7631a3b3d2ba19ff","repo":"docling-project/docling","slug":"mps-is-not-available-in-the-system-please-ensure","errorCode":null,"errorMessage":"MPS is not available in the system. Please ensure you are running on Apple Silicon with MPS support, or use --device auto/cpu.","messagePattern":"MPS is not available in the system\\. Please ensure you are running on Apple Silicon with MPS support, or use --device auto/cpu\\.","errorType":"exception","errorClass":"AcceleratorDeviceNotAvailableError","httpStatus":null,"severity":"error","filePath":"docling/utils/accelerator_utils.py","lineNumber":102,"sourceCode":"        else:\n            raise AcceleratorDeviceNotAvailableError(\n                \"CUDA is not available in the system. \"\n                \"Please ensure PyTorch with CUDA support is installed, or use --device auto/cpu.\"\n            )\n\n    elif accelerator_device == AcceleratorDevice.MPS.value:\n        if (\n            supported_devices is not None\n            and AcceleratorDevice.MPS not in supported_devices\n        ):\n            raise AcceleratorDeviceNotAvailableError(\n                f\"MPS is not supported by this model. Supported devices: {[d.value for d in supported_devices]}\"\n            )\n\n        if has_mps:\n            device = \"mps\"\n        else:\n            raise AcceleratorDeviceNotAvailableError(\n                \"MPS is not available in the system. \"\n                \"Please ensure you are running on Apple Silicon with MPS support, or use --device auto/cpu.\"\n            )\n\n    elif accelerator_device == AcceleratorDevice.XPU.value:\n        if (\n            supported_devices is not None\n            and AcceleratorDevice.XPU not in supported_devices\n        ):\n            raise AcceleratorDeviceNotAvailableError(\n                f\"XPU is not supported by this model. Supported devices: {[d.value for d in supported_devices]}\"\n            )\n\n        if has_xpu:\n            device = \"xpu\"\n        else:\n            raise AcceleratorDeviceNotAvailableError(\n                \"XPU is not available in the system. \"","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/accelerator_utils.py#L84-L120","documentation":"AcceleratorDeviceNotAvailableError raised by decide_device() when the user requests 'mps' but torch.backends.mps.is_built() or torch.backends.mps.is_available() is false. MPS exists only on Apple Silicon macOS with a sufficiently new PyTorch; this error means the runtime cannot provide MPS at all.","triggerScenarios":"Setting accelerator_device='mps' on Intel Macs, Linux/Windows boxes, or macOS with an old PyTorch that lacks MPS; also when supported_devices filtering removed MPS before the availability check.","commonSituations":"Sharing config between Mac and Linux machines; old torch version (<1.12) predating MPS; macOS version too old; running in a Linux container with a Mac-authored config file.","solutions":["Confirm platform: MPS requires Apple Silicon (M1/M2/M3) macOS and PyTorch >= 1.12 — check python -c \"import torch; print(torch.backends.mps.is_available())\"","Upgrade PyTorch to a recent release","Switch to accelerator_device='auto' or 'cpu' on non-Apple hardware","Keep per-machine device settings (env var / config override) instead of one shared value"],"exampleFix":"# before\naccelerator_options.accelerator_device = \"mps\"  # on Linux\n\n# after\naccelerator_options.accelerator_device = \"auto\"  # picks cpu on this host","handlingStrategy":"validation","validationCode":"import torch\n\nmps_ok = torch.backends.mps.is_built() and torch.backends.mps.is_available()\nif not mps_ok:\n    accelerator_options.accelerator_device = \"auto\"","typeGuard":"def mps_available() -> bool:\n    import torch\n    return torch.backends.mps.is_built() and torch.backends.mps.is_available()","tryCatchPattern":"from docling.exceptions import AcceleratorDeviceNotAvailableError\n\ntry:\n    device = decide_device(\"mps\")\nexcept AcceleratorDeviceNotAvailableError:\n    device = decide_device(\"auto\")","preventionTips":["Guard MPS usage with torch.backends.mps.is_available() at startup","Use PyTorch >= 1.12 on Apple Silicon","Keep device settings per-host (env/config), not in shared artifacts","'auto' is the portable default across Mac/Linux/Windows"],"tags":["mps","accelerator","environment","apple-silicon","pytorch"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}