docling-project/docling · error · AcceleratorDeviceNotAvailableError

Invalid CUDA device format '{accelerator_device}'. Use 'cuda

Error message

Invalid CUDA device format '{accelerator_device}'. Use 'cuda' or 'cuda:N' where N is a valid device index.

What it means

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.

Source

Thrown at docling/utils/accelerator_utils.py:80

            )

        if has_cuda:
            # if cuda device index specified extract device id
            parts = accelerator_device.split(":")
            if len(parts) == 2 and parts[1].isdigit():
                # select cuda device's id
                cuda_index = int(parts[1])
                if cuda_index < torch.cuda.device_count():
                    device = f"cuda:{cuda_index}"
                else:
                    raise AcceleratorDeviceNotAvailableError(
                        f"CUDA device 'cuda:{cuda_index}' is not available. "
                        f"Available CUDA devices: 0-{torch.cuda.device_count() - 1}"
                    )
            elif len(parts) == 1:  # just "cuda"
                device = "cuda:0"
            else:
                raise AcceleratorDeviceNotAvailableError(
                    f"Invalid CUDA device format '{accelerator_device}'. "
                    f"Use 'cuda' or 'cuda:N' where N is a valid device index."
                )
        else:
            raise AcceleratorDeviceNotAvailableError(
                "CUDA is not available in the system. "
                "Please ensure PyTorch with CUDA support is installed, or use --device auto/cpu."
            )

    elif accelerator_device == AcceleratorDevice.MPS.value:
        if (
            supported_devices is not None
            and AcceleratorDevice.MPS not in supported_devices
        ):
            raise AcceleratorDeviceNotAvailableError(
                f"MPS is not supported by this model. Supported devices: {[d.value for d in supported_devices]}"
            )

View on GitHub (pinned to 61d76f1ff3)

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

Example fix

# before
accelerator_options.accelerator_device = f"cuda:{gpu_slot}"  # gpu_slot = "0,1"

# after
accelerator_options.accelerator_device = f"cuda:{gpu_ids[0]}"  # single integer index

Defensive patterns

Strategy: validation

Validate before calling

import re

if not re.fullmatch(r"cuda(:\d+)?", accelerator_options.accelerator_device or ""):
    accelerator_options.accelerator_device = "auto"

Type guard

import re

def is_valid_device_string(device: str) -> bool:
    return bool(re.fullmatch(r"(auto|cpu|cuda(:\d+)?|mps|xpu)", device or ""))

Try / catch

from docling.exceptions import AcceleratorDeviceNotAvailableError

try:
    device = decide_device(requested)
except AcceleratorDeviceNotAvailableError:
    device = decide_device("auto")

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/005840ffe71539b6. Report an issue: GitHub.