{"record":{"id":"6cefb8cf8ce8f2ce","repo":"docling-project/docling","slug":"cuda-device-cuda-cuda-index-is-not-available","errorCode":null,"errorMessage":"CUDA device 'cuda:{cuda_index}' is not available. Available CUDA devices: 0-{torch.cuda.device_count() - 1}","messagePattern":"CUDA device 'cuda:(.+?)' is not available\\. Available CUDA devices: 0-(.+?)","errorType":"exception","errorClass":"AcceleratorDeviceNotAvailableError","httpStatus":null,"severity":"error","filePath":"docling/utils/accelerator_utils.py","lineNumber":73,"sourceCode":"    elif accelerator_device.startswith(\"cuda\"):\n        if (\n            supported_devices is not None\n            and AcceleratorDevice.CUDA not in supported_devices\n        ):\n            raise AcceleratorDeviceNotAvailableError(\n                f\"CUDA is not supported by this model. Supported devices: {[d.value for d in supported_devices]}\"\n            )\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 (","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/accelerator_utils.py#L55-L91","documentation":"AcceleratorDeviceNotAvailableError raised by decide_device() when the user requests 'cuda:N' with a numeric index N that is >= torch.cuda.device_count(). CUDA is present, but the requested GPU index does not exist on this machine (valid indices are 0..device_count-1).","triggerScenarios":"Setting accelerator_device='cuda:1' (or higher) on a machine with a single GPU; hardcoding a device index from a different node (multi-GPU box -> single-GPU container); CUDA_VISIBLE_DEVICES restricting visibility so device_count is smaller than the physical count.","commonSituations":"Porting configs between machines with different GPU counts; Docker with CUDA_VISIBLE_DEVICES=0 making 'cuda:1' invalid; driver/runtime problems reducing visible devices.","solutions":["Use a valid index: check torch.cuda.device_count() and pick 0..N-1, or just 'cuda' (defaults to cuda:0)","Inspect CUDA_VISIBLE_DEVICES in the environment — remapping may have hidden GPUs","Verify with nvidia-smi how many GPUs the process can actually see","Prefer 'cuda' without an index for portable configurations"],"exampleFix":"# before\naccelerator_options.accelerator_device = \"cuda:1\"  # single-GPU machine\n\n# after\naccelerator_options.accelerator_device = \"cuda\"  # resolves to cuda:0","handlingStrategy":"validation","validationCode":"import torch\n\nif accelerator_options.accelerator_device.startswith(\"cuda:\"):\n    idx = int(accelerator_options.accelerator_device.split(\":\")[1])\n    if idx >= torch.cuda.device_count():\n        accelerator_options.accelerator_device = \"cuda\"  # clamp to cuda:0","typeGuard":"def valid_cuda_index(device: str) -> bool:\n    if not device.startswith(\"cuda:\"):\n        return True\n    suffix = device.split(\":\", 1)[1]\n    return suffix.isdigit() and int(suffix) < torch.cuda.device_count()","tryCatchPattern":"from docling.exceptions import AcceleratorDeviceNotAvailableError\n\ntry:\n    device = decide_device(\"cuda:2\")\nexcept AcceleratorDeviceNotAvailableError:\n    device = decide_device(\"cuda\")  # fall back to default GPU","preventionTips":["Use bare 'cuda' unless you specifically need multi-GPU sharding","Check torch.cuda.device_count() (after CUDA_VISIBLE_DEVICES remapping) before pinning indices","Never hardcode GPU indices in shared configs — make them env-driven","Remember CUDA_VISIBLE_DEVICES remaps indices: host GPU 2 may be cuda:0 inside the container"],"tags":["cuda","accelerator","configuration","hardware"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}