docling-project/docling · error · AcceleratorDeviceNotAvailableError

MPS is not supported by this model. Supported devices: {[d.v

Error message

MPS is not supported by this model. Supported devices: {[d.value for d in supported_devices]}

What it means

AcceleratorDeviceNotAvailableError raised by decide_device() when the user explicitly requests 'mps' but the model's supported_devices list excludes AcceleratorDevice.MPS. Like the CUDA twin, this is a model-capability mismatch: the pipeline stage being initialized cannot run on Apple Silicon MPS regardless of whether MPS exists.

Source

Thrown at docling/utils/accelerator_utils.py:95

            elif len(parts) == 1:  # just "cuda"
                device = "cuda:0"
            else:
                raise AcceleratorDeviceNotAvailableError(
                    f"Invalid CUDA device format '{accelerator_device}'. "
                    f"Use 'cuda' or 'cuda:N' where N is a valid device index."
                )
        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]}"

View on GitHub (pinned to 61d76f1ff3)

Solutions

Use accelerator_device='auto', which silently demotes MPS for models that do not support it
Check the model stage's documentation/source for its supported_devices and align the request
Set the device per-stage instead of globally if only one component rejects MPS
Update docling — device support for specific models changes between releases

Example fix

# before
accelerator_options.accelerator_device = "mps"

# after
accelerator_options.accelerator_device = "auto"

Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.accelerator_options import AcceleratorDevice

supported = {d.value for d in model_supported_devices or []}
if accelerator_options.accelerator_device == "mps" and supported and "mps" not in supported:
    accelerator_options.accelerator_device = "auto"

Type guard

def mps_supported(supported: set[str]) -> bool:
    return "mps" in supported

Try / catch

from docling.exceptions import AcceleratorDeviceNotAvailableError

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

Prevention

Use 'auto' on mixed Mac fleets — it demotes MPS per model
Check the specific model stage's supported device list before forcing MPS
Set device per stage when only some components accept MPS
Recheck after upgrading docling — device support sets change

When it happens

Trigger: Setting accelerator_device='mps' in pipeline options or via CLI while initializing a model stage whose constructor passes supported_devices without MPS (e.g. a CUDA/CPU-only model spec).

Common situations: Enabling MPS globally on a Mac while a specific pipeline stage (certain table/OCR backends) does not support it; version changes that restrict a model's device set; custom models added without MPS support.

Related errors

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