{"record":{"id":"75342ad0fbac510b","repo":"docling-project/docling","slug":"invalid-device-option-use-auto-cpu-mps","errorCode":null,"errorMessage":"Invalid device option. Use `auto`, `cpu`, `mps`, `xpu`, `cuda`, or `cuda:N`.","messagePattern":"Invalid device option\\. Use `auto`, `cpu`, `mps`, `xpu`, `cuda`, or `cuda:N`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/datamodel/accelerator_options.py","lineNumber":76,"sourceCode":"        Field(\n            description=(\n                \"Enable Flash Attention 2 optimization for CUDA devices. \"\n                \"Provides significant speedup and memory reduction for \"\n                \"transformer models on compatible NVIDIA GPUs (Ampere or newer). \"\n                \"Requires flash-attn package installation. Can be set via \"\n                \"DOCLING_CUDA_USE_FLASH_ATTENTION2 environment variable.\"\n            )\n        ),\n    ] = False\n\n    @field_validator(\"device\")\n    def validate_device(cls, value):\n        # \"auto\", \"cpu\", \"cuda\", \"mps\", \"xpu\", or \"cuda:N\"\n        if value in {d.value for d in AcceleratorDevice} or re.match(\n            r\"^cuda(:\\d+)?$\", value\n        ):\n            return value\n        raise ValueError(\n            \"Invalid device option. Use `auto`, `cpu`, `mps`, `xpu`, `cuda`, \"\n            \"or `cuda:N`.\"\n        )\n\n    @model_validator(mode=\"before\")\n    @classmethod\n    def check_alternative_envvars(cls, data: Any) -> Any:\n        r\"\"\"\n        Set num_threads from the \"alternative\" envvar OMP_NUM_THREADS.\n        The alternative envvar is used only if it is valid and the regular\n        envvar is not set.\n\n        Notice: The standard pydantic settings mechanism with parameter\n        \"aliases\" does not provide the same functionality. In case the alias\n        envvar is set and the user tries to override the parameter in settings\n        initialization, Pydantic treats the parameter provided in __init__()\n        as an extra input instead of simply overwriting the evvar value for\n        that parameter.","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/datamodel/accelerator_options.py#L58-L94","documentation":"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.","triggerScenarios":"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.","commonSituations":"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').","solutions":["Use one of the exact accepted values: auto, cpu, mps, xpu, cuda, or cuda:N (e.g., cuda:1).","Lowercase and strip the value before assigning: device.strip().lower().","If sourcing from config/env, validate with the same regex ^cuda(:\\d+)?$ or enum membership first.","For Apple Silicon use 'mps'; for Intel GPUs use 'xpu'."],"exampleFix":"# before\nopts = AcceleratorOptions(num_threads=8, device='CUDA:0')  # ValueError\n\n# after\nopts = AcceleratorOptions(num_threads=8, device='cuda:0')","handlingStrategy":"validation","validationCode":"import re\nfrom docling.datamodel.accelerator_options import AcceleratorDevice\n\ndef normalize_device(v: str) -> str:\n    v = v.strip().lower()\n    if v in {d.value for d in AcceleratorDevice} or re.match(r'^cuda(:\\d+)?$', v):\n        return v\n    raise ValueError(f'unsupported device: {v!r}')","typeGuard":"def is_valid_device(v: str) -> bool:\n    v = v.strip().lower()\n    return v in {d.value for d in AcceleratorDevice} or bool(re.match(r'^cuda(:\\d+)?$', v))","tryCatchPattern":null,"preventionTips":["Normalize device strings (strip + lower) from env vars/config before use.","Accept only auto/cpu/mps/xpu/cuda/cuda:N.","Fail fast on config load, not at pipeline construction."],"tags":["accelerator","validation","pydantic","cuda"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}