docling-project/docling · error · AcceleratorDeviceNotAvailableError

MPS is not available in the system. Please ensure you are ru

Error message

MPS is not available in the system. Please ensure you are running on Apple Silicon with MPS support, or use --device auto/cpu.

What it means

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.

Source

Thrown at docling/utils/accelerator_utils.py:102

        else:
            raise AcceleratorDeviceNotAvailableError(
                "CUDA is not available in the system. "
                "Please ensure PyTorch with CUDA support is installed, or use --device auto/cpu."
            )

    elif accelerator_device == AcceleratorDevice.MPS.value:
        if (
            supported_devices is not None
            and AcceleratorDevice.MPS not in supported_devices
        ):
            raise AcceleratorDeviceNotAvailableError(
                f"MPS is not supported by this model. Supported devices: {[d.value for d in supported_devices]}"
            )

        if has_mps:
            device = "mps"
        else:
            raise AcceleratorDeviceNotAvailableError(
                "MPS is not available in the system. "
                "Please ensure you are running on Apple Silicon with MPS support, or use --device auto/cpu."
            )

    elif accelerator_device == AcceleratorDevice.XPU.value:
        if (
            supported_devices is not None
            and AcceleratorDevice.XPU not in supported_devices
        ):
            raise AcceleratorDeviceNotAvailableError(
                f"XPU is not supported by this model. Supported devices: {[d.value for d in supported_devices]}"
            )

        if has_xpu:
            device = "xpu"
        else:
            raise AcceleratorDeviceNotAvailableError(
                "XPU is not available in the system. "

View on GitHub (pinned to 61d76f1ff3)

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

Example fix

# before
accelerator_options.accelerator_device = "mps"  # on Linux

# after
accelerator_options.accelerator_device = "auto"  # picks cpu on this host

Defensive patterns

Strategy: validation

Validate before calling

import torch

mps_ok = torch.backends.mps.is_built() and torch.backends.mps.is_available()
if not mps_ok:
    accelerator_options.accelerator_device = "auto"

Type guard

def mps_available() -> bool:
    import torch
    return torch.backends.mps.is_built() and torch.backends.mps.is_available()

Try / catch

from docling.exceptions import AcceleratorDeviceNotAvailableError

try:
    device = decide_device("mps")
except AcceleratorDeviceNotAvailableError:
    device = decide_device("auto")

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/7631a3b3d2ba19ff. Report an issue: GitHub.