{"record":{"id":"005840ffe71539b6","repo":"docling-project/docling","slug":"invalid-cuda-device-format-accelerator-device","errorCode":null,"errorMessage":"Invalid CUDA device format '{accelerator_device}'. Use 'cuda' or 'cuda:N' where N is a valid device index.","messagePattern":"Invalid CUDA device format '(.+?)'\\. Use 'cuda' or 'cuda:N' where N is a valid device index\\.","errorType":"exception","errorClass":"AcceleratorDeviceNotAvailableError","httpStatus":null,"severity":"error","filePath":"docling/utils/accelerator_utils.py","lineNumber":80,"sourceCode":"            )\n\n        if has_cuda:\n            # if cuda device index specified extract device id\n            parts = accelerator_device.split(\":\")\n            if len(parts) == 2 and parts[1].isdigit():\n                # select cuda device's id\n                cuda_index = int(parts[1])\n                if cuda_index < torch.cuda.device_count():\n                    device = f\"cuda:{cuda_index}\"\n                else:\n                    raise AcceleratorDeviceNotAvailableError(\n                        f\"CUDA device 'cuda:{cuda_index}' is not available. \"\n                        f\"Available CUDA devices: 0-{torch.cuda.device_count() - 1}\"\n                    )\n            elif len(parts) == 1:  # just \"cuda\"\n                device = \"cuda:0\"\n            else:\n                raise AcceleratorDeviceNotAvailableError(\n                    f\"Invalid CUDA device format '{accelerator_device}'. \"\n                    f\"Use 'cuda' or 'cuda:N' where N is a valid device index.\"\n                )\n        else:\n            raise AcceleratorDeviceNotAvailableError(\n                \"CUDA is not available in the system. \"\n                \"Please ensure PyTorch with CUDA support is installed, or use --device auto/cpu.\"\n            )\n\n    elif accelerator_device == AcceleratorDevice.MPS.value:\n        if (\n            supported_devices is not None\n            and AcceleratorDevice.MPS not in supported_devices\n        ):\n            raise AcceleratorDeviceNotAvailableError(\n                f\"MPS is not supported by this model. Supported devices: {[d.value for d in supported_devices]}\"\n            )\n","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/accelerator_utils.py#L62-L98","documentation":"AcceleratorDeviceNotAvailableError raised by decide_device() when the accelerator_device string starts with 'cuda' but does not match the allowed shapes: it must be exactly 'cuda' (one part) or 'cuda:N' with a numeric N (two parts, digits only). Anything else — 'cuda:abc', 'cuda:0:1', 'cuda:' — hits this branch. Note: an out-of-range numeric index raises the 'not available' error instead.","triggerScenarios":"Passing a malformed device string such as accelerator_device='cuda:01x', 'cuda-1', 'cuda:gpu0', or 'cuda:0,1' in pipeline options or on the CLI; typos like trailing whitespace around the index ('cuda: 1' fails isdigit).","commonSituations":"Copy-paste of device specs from other frameworks (e.g. CUDA_VISIBLE_DEVICES-style lists or torch device tuples); user-built strings via f-string concatenation that produce extra segments; CLI argument typos.","solutions":["Use exactly 'cuda' or 'cuda:<integer>' (e.g. 'cuda:0')","Validate the string against the pattern ^cuda(:\\d+)?$ before passing it","If you need multiple GPUs, that is not expressed here — pick one index per pipeline instance","Check for whitespace/case issues in programmatically built device strings"],"exampleFix":"# before\naccelerator_options.accelerator_device = f\"cuda:{gpu_slot}\"  # gpu_slot = \"0,1\"\n\n# after\naccelerator_options.accelerator_device = f\"cuda:{gpu_ids[0]}\"  # single integer index","handlingStrategy":"validation","validationCode":"import re\n\nif not re.fullmatch(r\"cuda(:\\d+)?\", accelerator_options.accelerator_device or \"\"):\n    accelerator_options.accelerator_device = \"auto\"","typeGuard":"import re\n\ndef is_valid_device_string(device: str) -> bool:\n    return bool(re.fullmatch(r\"(auto|cpu|cuda(:\\d+)?|mps|xpu)\", device or \"\"))","tryCatchPattern":"from docling.exceptions import AcceleratorDeviceNotAvailableError\n\ntry:\n    device = decide_device(requested)\nexcept AcceleratorDeviceNotAvailableError:\n    device = decide_device(\"auto\")","preventionTips":["Validate device strings with the regex ^cuda(:\\d+)?$ before use","Build device strings from integers, never from free-form config values","Strip whitespace on values read from env/config files","Prefer the AcceleratorDevice enum over raw strings"],"tags":["cuda","accelerator","input-validation","configuration"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}