docling-project/docling · error · AcceleratorDeviceNotAvailableError

Unknown device option '{accelerator_device}'. Valid options

Error message

Unknown device option '{accelerator_device}'. Valid options are: auto, cpu, cuda, mps, xpu, or cuda:N

What it means

AcceleratorDeviceNotAvailableError raised by decide_device() when accelerator_device matches none of the known options ('auto', 'cpu', values starting with 'cuda', 'mps', 'xpu'). The function lists the valid values in the message: auto, cpu, cuda, mps, xpu, or cuda:N. It is a pure input-validation failure on the device string.

Source

Thrown at docling/utils/accelerator_utils.py:128

            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"
        )

    _log.info("Accelerator device: '%s'", device)
    return device

View on GitHub (pinned to 61d76f1ff3)

Solutions

Use one of: 'auto', 'cpu', 'cuda', 'cuda:N', 'mps', 'xpu'
Pass the AcceleratorDevice enum member (e.g. AcceleratorDevice.AUTO) instead of a raw string where the API accepts it
Strip/normalize strings read from configs or environment variables
Check for case: values are lowercase

Example fix

# before
accelerator_options.accelerator_device = "GPU"  # ValueError-ish: unknown device option

# after
from docling.datamodel.accelerator_options import AcceleratorDevice
accelerator_options.accelerator_device = AcceleratorDevice.AUTO.value  # 'auto'

Defensive patterns

Strategy: validation

Validate before calling

import re

VALID = re.compile(r"(auto|cpu|cuda|cuda:\d+|mps|xpu)\Z")
if not VALID.fullmatch(accelerator_options.accelerator_device or ""):
    accelerator_options.accelerator_device = "auto"

Type guard

import re

VALID_DEVICES = re.compile(r"(auto|cpu|cuda|cuda:\d+|mps|xpu)\Z")

def is_valid_accelerator_device(value: str) -> bool:
    return isinstance(value, str) and bool(VALID_DEVICES.fullmatch(value))

Try / catch

from docling.exceptions import AcceleratorDeviceNotAvailableError

try:
    device = decide_device(raw_device_string)
except AcceleratorDeviceNotAvailableError:
    device = decide_device("auto")  # or log & fail fast on bad user input

Prevention

Normalize device strings (strip + lowercase) from env vars and config files
Validate user-supplied device names against the regex before constructing pipeline options
Pass the AcceleratorDevice enum instead of strings where accepted
Reject unknown values at the config boundary, not deep in model init

When it happens

Trigger: Passing accelerator_device values like 'gpu', 'CUDA' (case-sensitive), 'metal', 'tpu', an empty string, or a typo like 'cudaa' in PdfPipelineOptions.accelerator_options or the CLI --device flag.

Common situations: Assuming torch device names (e.g. 'cuda:0' works but 'mkldnn' or 'vulkan' do not); uppercase variants from env vars; whitespace-padded strings from config files; confusing AcceleratorDevice enum objects with raw strings in older releases.

Related errors

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