docling-project/docling · error · AcceleratorDeviceNotAvailableError

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

Error message

CUDA 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 a CUDA device (accelerator_device startswith 'cuda') but the model/pipeline declares supported_devices that excludes AcceleratorDevice.CUDA. It is a hard configuration error: the chosen model cannot run on CUDA regardless of hardware availability.

Source

Thrown at docling/utils/accelerator_utils.py:60

            _log.info(
                f"Removing XPU from available devices because it is not in {supported_devices=}"
            )
            has_xpu = False

    if accelerator_device == AcceleratorDevice.AUTO.value:  # Handle 'auto'
        if has_cuda:
            device = "cuda:0"
        elif has_mps:
            device = "mps"
        elif has_xpu:
            device = "xpu"

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

        if has_cuda:
            # if cuda device index specified extract device id
            parts = accelerator_device.split(":")
            if len(parts) == 2 and parts[1].isdigit():
                # select cuda device's id
                cuda_index = int(parts[1])
                if cuda_index < torch.cuda.device_count():
                    device = f"cuda:{cuda_index}"
                else:
                    raise AcceleratorDeviceNotAvailableError(
                        f"CUDA device 'cuda:{cuda_index}' is not available. "
                        f"Available CUDA devices: 0-{torch.cuda.device_count() - 1}"
                    )
            elif len(parts) == 1:  # just "cuda"
                device = "cuda:0"

View on GitHub (pinned to 61d76f1ff3)

Solutions

Switch the pipeline/stage to a supported device: use accelerator_device='auto' or 'cpu' (auto silently demotes unsupported devices per model)
Check the model's documented supported devices and align accelerator_device accordingly
Configure accelerator device per-model/stage rather than globally if only one stage rejects CUDA
Upgrade docling — supported device sets occasionally widen in newer releases

Example fix

# before
accelerator_options.accelerator_device = "cuda"

# after
accelerator_options.accelerator_device = "auto"  # falls back per-model supported devices

Defensive patterns

Strategy: validation

Validate before calling

from docling.datamodel.accelerator_options import AcceleratorDevice

SUPPORTED = {d.value for d in model_supported_devices}  # from the model spec
if accelerator_options.accelerator_device.startswith("cuda") and "cuda" not in SUPPORTED:
    accelerator_options.accelerator_device = "auto"

Type guard

def device_supported(requested: str, supported: set[str]) -> bool:
    base = requested.split(":")[0]
    return requested in supported or base in supported

Try / catch

from docling.exceptions import AcceleratorDeviceNotAvailableError

try:
    device = decide_device(requested, supported_devices)
except AcceleratorDeviceNotAvailableError:
    device = decide_device("auto", supported_devices)  # per-model demotion

Prevention

Default to 'auto' — it demotes unsupported devices per model instead of raising
Consult each model stage's supported_devices before pinning a global device
Set devices per-stage when mixing CUDA and CPU-only models
Re-check supported devices after docling upgrades

When it happens

Trigger: Setting accelerator_options.accelerator_device='cuda' (or 'cuda:N') in PdfPipelineOptions (or --device cuda in the CLI) while the model being initialized passes supported_devices without CUDA — e.g. a CPU-only or MPS-only model spec in its constructor call to decide_device.

Common situations: Mixing third-party/custom model stages into a pipeline and assuming every model supports CUDA; newer model variants restricted to specific backends; passing a device globally via CLI while a specific stage does not support it.

Related errors

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