{"record":{"id":"6322415f29f5d135","repo":"docling-project/docling","slug":"unknown-device-option-accelerator-device-vali","errorCode":null,"errorMessage":"Unknown device option '{accelerator_device}'. Valid options are: auto, cpu, cuda, mps, xpu, or cuda:N","messagePattern":"Unknown device option '(.+?)'\\. Valid options are: auto, cpu, cuda, mps, xpu, or cuda:N","errorType":"exception","errorClass":"AcceleratorDeviceNotAvailableError","httpStatus":null,"severity":"error","filePath":"docling/utils/accelerator_utils.py","lineNumber":128,"sourceCode":"            and AcceleratorDevice.XPU not in supported_devices\n        ):\n            raise AcceleratorDeviceNotAvailableError(\n                f\"XPU is not supported by this model. Supported devices: {[d.value for d in supported_devices]}\"\n            )\n\n        if has_xpu:\n            device = \"xpu\"\n        else:\n            raise AcceleratorDeviceNotAvailableError(\n                \"XPU is not available in the system. \"\n                \"Please ensure PyTorch with Intel XPU support is installed, or use --device auto/cpu.\"\n            )\n\n    elif accelerator_device == AcceleratorDevice.CPU.value:\n        device = \"cpu\"\n\n    else:\n        raise AcceleratorDeviceNotAvailableError(\n            f\"Unknown device option '{accelerator_device}'. \"\n            f\"Valid options are: auto, cpu, cuda, mps, xpu, or cuda:N\"\n        )\n\n    _log.info(\"Accelerator device: '%s'\", device)\n    return device\n","sourceCodeStart":110,"sourceCodeEnd":135,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/accelerator_utils.py#L110-L135","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\naccelerator_options.accelerator_device = \"GPU\"  # ValueError-ish: unknown device option\n\n# after\nfrom docling.datamodel.accelerator_options import AcceleratorDevice\naccelerator_options.accelerator_device = AcceleratorDevice.AUTO.value  # 'auto'","handlingStrategy":"validation","validationCode":"import re\n\nVALID = re.compile(r\"(auto|cpu|cuda|cuda:\\d+|mps|xpu)\\Z\")\nif not VALID.fullmatch(accelerator_options.accelerator_device or \"\"):\n    accelerator_options.accelerator_device = \"auto\"","typeGuard":"import re\n\nVALID_DEVICES = re.compile(r\"(auto|cpu|cuda|cuda:\\d+|mps|xpu)\\Z\")\n\ndef is_valid_accelerator_device(value: str) -> bool:\n    return isinstance(value, str) and bool(VALID_DEVICES.fullmatch(value))","tryCatchPattern":"from docling.exceptions import AcceleratorDeviceNotAvailableError\n\ntry:\n    device = decide_device(raw_device_string)\nexcept AcceleratorDeviceNotAvailableError:\n    device = decide_device(\"auto\")  # or log & fail fast on bad user input","preventionTips":["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"],"tags":["accelerator","input-validation","configuration"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}