{"record":{"id":"7b83f702f97dc179","repo":"docling-project/docling","slug":"cuda-is-not-available-in-the-system-please-ensure","errorCode":null,"errorMessage":"CUDA is not available in the system. Please ensure PyTorch with CUDA support is installed, or use --device auto/cpu.","messagePattern":"CUDA is not available in the system\\. Please ensure PyTorch with CUDA support is installed, or use --device auto/cpu\\.","errorType":"exception","errorClass":"AcceleratorDeviceNotAvailableError","httpStatus":null,"severity":"error","filePath":"docling/utils/accelerator_utils.py","lineNumber":85,"sourceCode":"            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\n        if has_mps:\n            device = \"mps\"\n        else:\n            raise AcceleratorDeviceNotAvailableError(\n                \"MPS is not available in the system. \"","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/accelerator_utils.py#L67-L103","documentation":"AcceleratorDeviceNotAvailableError raised by decide_device() when the user explicitly requests a CUDA device but torch reports CUDA as unavailable (torch.backends.cuda.is_built() is false or torch.cuda.is_available() is false) — including the case where supported_devices removed CUDA. The machine/build cannot serve the request, so the error suggests installing a CUDA-enabled PyTorch or switching to auto/cpu.","triggerScenarios":"Setting accelerator_device='cuda'/'cuda:N' while running a CPU-only PyTorch wheel (typical default pip install), on a machine without an NVIDIA GPU, with a missing NVIDIA driver, or with a CUDA version mismatch between torch and the driver.","commonSituations":"Installing docling via pip which pulls the CPU torch wheel, then enabling CUDA; CUDA driver too old for the installed torch CUDA runtime; GPU node drained/detached; running in a container without GPU passthrough (no nvidia-runtime); CUDA_VISIBLE_DEVICES set to empty string.","solutions":["Verify the environment: python -c \"import torch; print(torch.cuda.is_available(), torch.version.cuda)\" and nvidia-smi","Install a CUDA-enabled PyTorch build matching your CUDA toolkit (e.g. the cu121 wheel index)","Or switch the config to accelerator_device='auto' or 'cpu' to run on CPU","In containers, ensure GPU passthrough (nvidia-container-toolkit / --gpus all) and that CUDA_VISIBLE_DEVICES is not empty"],"exampleFix":"# before\naccelerator_options.accelerator_device = \"cuda\"  # CPU-only torch installed\n\n# after\naccelerator_options.accelerator_device = \"auto\"  # gracefully picks best available device","handlingStrategy":"validation","validationCode":"import torch\n\ncuda_ok = torch.backends.cuda.is_built() and torch.cuda.is_available()\nif not cuda_ok:\n    accelerator_options.accelerator_device = \"cpu\"  # or \"auto\"","typeGuard":"def cuda_available() -> bool:\n    import torch\n    return torch.backends.cuda.is_built() and torch.cuda.is_available()","tryCatchPattern":"from docling.exceptions import AcceleratorDeviceNotAvailableError\n\ntry:\n    device = decide_device(\"cuda\")\nexcept AcceleratorDeviceNotAvailableError:\n    device = decide_device(\"auto\")  # CPU fallback","preventionTips":["Smoke-test torch.cuda.is_available() at startup when CUDA is requested","Install CUDA-enabled torch wheels matching your driver's CUDA version","In Docker, run with --gpus all / nvidia-container-toolkit","Check CUDA_VISIBLE_DEVICES is not empty or '-1' in the environment"],"tags":["cuda","accelerator","environment","hardware","pytorch"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}