docling-project/docling · error · ValueError

Invalid device option. Use `auto`, `cpu`, `mps`, `xpu`, `cud

Error message

Invalid device option. Use `auto`, `cpu`, `mps`, `xpu`, `cuda`, or `cuda:N`.

What it means

Pydantic field_validator on AcceleratorOptions.device rejecting any device string that is not exactly one of the AcceleratorDevice enum values ('auto','cpu','mps','xpu','cuda') or a 'cuda:N' pattern with N being digits. It fires at model construction time, so misconfigured accelerators fail fast before any model loads.

Source

Thrown at docling/datamodel/accelerator_options.py:76

        Field(
            description=(
                "Enable Flash Attention 2 optimization for CUDA devices. "
                "Provides significant speedup and memory reduction for "
                "transformer models on compatible NVIDIA GPUs (Ampere or newer). "
                "Requires flash-attn package installation. Can be set via "
                "DOCLING_CUDA_USE_FLASH_ATTENTION2 environment variable."
            )
        ),
    ] = False

    @field_validator("device")
    def validate_device(cls, value):
        # "auto", "cpu", "cuda", "mps", "xpu", or "cuda:N"
        if value in {d.value for d in AcceleratorDevice} or re.match(
            r"^cuda(:\d+)?$", value
        ):
            return value
        raise ValueError(
            "Invalid device option. Use `auto`, `cpu`, `mps`, `xpu`, `cuda`, "
            "or `cuda:N`."
        )

    @model_validator(mode="before")
    @classmethod
    def check_alternative_envvars(cls, data: Any) -> Any:
        r"""
        Set num_threads from the "alternative" envvar OMP_NUM_THREADS.
        The alternative envvar is used only if it is valid and the regular
        envvar is not set.

        Notice: The standard pydantic settings mechanism with parameter
        "aliases" does not provide the same functionality. In case the alias
        envvar is set and the user tries to override the parameter in settings
        initialization, Pydantic treats the parameter provided in __init__()
        as an extra input instead of simply overwriting the evvar value for
        that parameter.

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use one of the exact accepted values: auto, cpu, mps, xpu, cuda, or cuda:N (e.g., cuda:1).
2. Lowercase and strip the value before assigning: device.strip().lower().
3. If sourcing from config/env, validate with the same regex ^cuda(:\d+)?$ or enum membership first.
4. For Apple Silicon use 'mps'; for Intel GPUs use 'xpu'.

Example fix

# before
opts = AcceleratorOptions(num_threads=8, device='CUDA:0')  # ValueError

# after
opts = AcceleratorOptions(num_threads=8, device='cuda:0')

import re
from docling.datamodel.accelerator_options import AcceleratorDevice

def normalize_device(v: str) -> str:
    v = v.strip().lower()
    if v in {d.value for d in AcceleratorDevice} or re.match(r'^cuda(:\d+)?$', v):
        return v
    raise ValueError(f'unsupported device: {v!r}')

def is_valid_device(v: str) -> bool:
    v = v.strip().lower()
    return v in {d.value for d in AcceleratorDevice} or bool(re.match(r'^cuda(:\d+)?$', v))

When it happens

Trigger: Setting AcceleratorOptions(device='cuda:0 ') with trailing space, 'CUDA' uppercase, 'cuda-1', 'gpu', 'metal', 'cuda:device 1', or any non-enum string; reading the device from an env var or config file that contains an unsupported value and passing it into AcceleratorOptions or a pipeline options object.

Common situations: Users writing 'GPU' or 'cuda:01:' style typos in YAML/JSON configs; NVIDIA container envs where device comes from an env var with unexpected formatting; MPS confusion ('apple-silicon' instead of 'mps').

Related errors

• record_type_field is required for a layout with several reco
• every record needs a selector when record_type_field is set
• record selectors must be unique
• set either layout or layout_file, not both
• Model `{self.repo_id}` is English-only and does not support

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