docling-project/docling · error · AcceleratorDeviceNotAvailableError

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

Error message

XPU 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 'xpu' (Intel GPU) but the model's supported_devices list excludes AcceleratorDevice.XPU. It is the model-capability variant of the XPU checks: even on an Intel GPU machine, the specific model stage cannot use XPU.

Source

Thrown at docling/utils/accelerator_utils.py:112

        ):
            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. "
                "Please ensure PyTorch with Intel XPU support is installed, or use --device auto/cpu."
            )

    elif accelerator_device == AcceleratorDevice.CPU.value:
        device = "cpu"

    else:
        raise AcceleratorDeviceNotAvailableError(
            f"Unknown device option '{accelerator_device}'. "
            f"Valid options are: auto, cpu, cuda, mps, xpu, or cuda:N"

View on GitHub (pinned to 61d76f1ff3)

Solutions

Use accelerator_device='auto' — it removes unsupported devices per model instead of raising
Check the model's supported device list and request one it supports
Configure the device per pipeline stage
Upgrade docling/torch — XPU support coverage improves over releases

Example fix

# before
accelerator_options.accelerator_device = "xpu"

# after
accelerator_options.accelerator_device = "auto"

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

def xpu_supported(supported: set[str]) -> bool:
    return "xpu" in supported

Try / catch

from docling.exceptions import AcceleratorDeviceNotAvailableError

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

Prevention

Use 'auto' unless every stage in your pipeline is known XPU-capable
Verify the model's supported_devices before pinning XPU
Track release notes — XPU coverage per model is still expanding
Scope XPU config to Intel GPU nodes only

When it happens

Trigger: Setting accelerator_device='xpu' while a pipeline stage passes supported_devices without XPU to decide_device (common: many vision/table models were only validated on CUDA/CPU).

Common situations: Early adoption of Intel GPU (Arc/Data Center Max) acceleration with model stages not yet XPU-enabled; enabling XPU globally via CLI while one stage doesn't support it.

Related errors

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