{"record":{"id":"6b64a911d698cf4b","repo":"unslothai/unsloth","slug":"gpu-ids-list-gpu-ids-is-only-supported-on-cuda","errorCode":null,"errorMessage":"gpu_ids {list(gpu_ids)} is only supported on CUDA and Intel XPU devices, but the current backend is '{get_device().value}'.","messagePattern":"gpu_ids (.+?) is only supported on CUDA and Intel XPU devices, but the current backend is '(.+?)'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/hardware/hardware.py","lineNumber":3387,"sourceCode":"    optimizer: str = \"adamw_8bit\",\n) -> tuple[Optional[list[int]], Dict[str, Any]]:\n    \"\"\"Resolve which physical GPUs to use for a model load.\n\n    GPU selection modes:\n      - **Explicit** (``gpu_ids=[5, 6, 7]``): caller chooses exact GPUs.\n        All listed GPUs are used and the model is sharded via\n        ``device_map=\"balanced\"``, even if it would fit on fewer. IDs are\n        validated against the parent-visible set.\n      - **Auto** (``gpu_ids=None`` or ``[]``): ``auto_select_gpu_ids``\n        estimates VRAM needs and picks the *minimum* GPUs needed,\n        preferring those with the most free memory.\n\n    The returned ``gpu_ids`` is later passed to ``get_device_map()`` (maps it\n    to a Hugging Face ``device_map`` string) and to ``apply_gpu_ids()`` in the\n    worker subprocess (narrows ``CUDA_VISIBLE_DEVICES`` before torch/CUDA init).\n    \"\"\"\n    if gpu_ids and get_device() not in (DeviceType.CUDA, DeviceType.XPU):\n        raise ValueError(\n            f\"gpu_ids {list(gpu_ids)} is only supported on CUDA and Intel XPU \"\n            f\"devices, but the current backend is '{get_device().value}'.\"\n        )\n\n    if gpu_ids:\n        resolved = resolve_requested_gpu_ids(gpu_ids)\n        metadata = {\n            \"selection_mode\": \"explicit\",\n            \"selected_gpu_ids\": resolved,\n        }\n        return resolved, metadata\n\n    selected_gpu_ids, metadata = auto_select_gpu_ids(\n        model_name,\n        hf_token = hf_token,\n        training_type = training_type,\n        load_in_4bit = load_in_4bit,\n        batch_size = batch_size,","sourceCodeStart":3369,"sourceCodeEnd":3405,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/hardware/hardware.py#L3369-L3405","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Drop gpu_ids (pass None or []) — selection is GPU-only; CPU backends ignore it.","Confirm the intended backend: check get_device().value and torch/driver installation if a GPU should be present.","Install/repair CUDA or XPU support (correct torch wheel, drivers) so the backend detects the GPU.","Gate GPU-selection calls in your code on the device type."],"exampleFix":"# before\nresolved, meta = select_gpu_ids([0])  # on CPU backend -> ValueError\n\n# after\nresolved, meta = select_gpu_ids([0] if get_device() in (DeviceType.CUDA, DeviceType.XPU) else None)","handlingStrategy":"type-guard","validationCode":"from utils.hardware.hardware import get_device, DeviceType\n\ndef supports_gpu_selection() -> bool:\n    return get_device() in (DeviceType.CUDA, DeviceType.XPU)\n\n# guard: gpu_ids = gpu_ids if supports_gpu_selection() else None","typeGuard":"def can_pass_gpu_ids(device) -> bool:\n    \"\"\"Explicit gpu_ids are only valid on CUDA/XPU backends.\"\"\"\n    return device in (DeviceType.CUDA, DeviceType.XPU)","tryCatchPattern":null,"preventionTips":["Gate explicit gpu_ids on backend type in shared scripts.","Verify GPU detection (drivers + correct torch build) before expecting CUDA/XPU.","Keep CPU/MPS dev configs separate from GPU production configs."],"tags":["gpu","backend","cpu","mps","hardware-detection"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}