unslothai/unsloth · error · ValueError

gpu_ids {list(gpu_ids)} is only supported on CUDA and Intel

Error message

gpu_ids {list(gpu_ids)} is only supported on CUDA and Intel XPU devices, but the current backend is '{get_device().value}'.

What it means

Raised at the top of the GPU-selection API (the function that validates explicit lists and supports auto mode) when gpu_ids are supplied but the detected device backend is anything other than CUDA or Intel XPU (e.g. CPU, MPS, Vulkan, ROCm variants not mapped to CUDA). It fails before any id validation because the whole selection mechanism only targets those two backends.

Source

Thrown at studio/backend/utils/hardware/hardware.py:3387

    optimizer: str = "adamw_8bit",
) -> tuple[Optional[list[int]], Dict[str, Any]]:
    """Resolve which physical GPUs to use for a model load.

    GPU selection modes:
      - **Explicit** (``gpu_ids=[5, 6, 7]``): caller chooses exact GPUs.
        All listed GPUs are used and the model is sharded via
        ``device_map="balanced"``, even if it would fit on fewer. IDs are
        validated against the parent-visible set.
      - **Auto** (``gpu_ids=None`` or ``[]``): ``auto_select_gpu_ids``
        estimates VRAM needs and picks the *minimum* GPUs needed,
        preferring those with the most free memory.

    The returned ``gpu_ids`` is later passed to ``get_device_map()`` (maps it
    to a Hugging Face ``device_map`` string) and to ``apply_gpu_ids()`` in the
    worker subprocess (narrows ``CUDA_VISIBLE_DEVICES`` before torch/CUDA init).
    """
    if gpu_ids and get_device() not in (DeviceType.CUDA, DeviceType.XPU):
        raise ValueError(
            f"gpu_ids {list(gpu_ids)} is only supported on CUDA and Intel XPU "
            f"devices, but the current backend is '{get_device().value}'."
        )

    if gpu_ids:
        resolved = resolve_requested_gpu_ids(gpu_ids)
        metadata = {
            "selection_mode": "explicit",
            "selected_gpu_ids": resolved,
        }
        return resolved, metadata

    selected_gpu_ids, metadata = auto_select_gpu_ids(
        model_name,
        hf_token = hf_token,
        training_type = training_type,
        load_in_4bit = load_in_4bit,
        batch_size = batch_size,

View on GitHub (pinned to 203007d190)

Solutions

1. Drop gpu_ids (pass None or []) — selection is GPU-only; CPU backends ignore it.
2. Confirm the intended backend: check get_device().value and torch/driver installation if a GPU should be present.
3. Install/repair CUDA or XPU support (correct torch wheel, drivers) so the backend detects the GPU.
4. Gate GPU-selection calls in your code on the device type.

Example fix

# before
resolved, meta = select_gpu_ids([0])  # on CPU backend -> ValueError

# after
resolved, meta = select_gpu_ids([0] if get_device() in (DeviceType.CUDA, DeviceType.XPU) else None)

from utils.hardware.hardware import get_device, DeviceType

def supports_gpu_selection() -> bool:
    return get_device() in (DeviceType.CUDA, DeviceType.XPU)

# guard: gpu_ids = gpu_ids if supports_gpu_selection() else None

def can_pass_gpu_ids(device) -> bool:
    """Explicit gpu_ids are only valid on CUDA/XPU backends."""
    return device in (DeviceType.CUDA, DeviceType.XPU)

When it happens

Trigger: Calling the gpu-selection API with a non-empty gpu_ids list on a machine whose backend resolves to cpu/mps/vulkan — e.g. no NVIDIA/Intel driver present, or a llama.cpp CPU/Vulkan build.

Common situations: Config reused from a GPU machine on a CPU-only box; Mac (MPS) development; Vulkan builds where this higher-level API deliberately does not apply (Vulkan ordinals are handled inside resolve_requested_gpu_ids instead); misdetected backend due to a broken torch install.

Related errors

• Export subprocess crashed during wait
• transformer_quant='{requested}' could not be used: {reason}.
• GPU selection is unavailable on this host: {exc}
• Requested GPU {wanted} but none of them are visible to this
• The current inference worker did not exit and still holds GP

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/6b64a911d698cf4b. Report an issue: GitHub.