Lightning-AI/pytorch-lightning · error · TypeError

GPUs should be a list

Error message

GPUs should be a list

What it means

`_determine_root_gpu_device` expects the GPU specification to already be a list (as produced by earlier parsing stages such as `_parse_gpu_ids`). If it receives anything other than None or a list (e.g. an int or string passed directly to this internal helper), it raises TypeError('GPUs should be a list').

Source

Thrown at src/lightning/fabric/utilities/device_parser.py:41

def _determine_root_gpu_device(gpus: list[_DEVICE]) -> Optional[_DEVICE]:
    """
    Args:
        gpus: Non-empty list of ints representing which GPUs to use

    Returns:
        Designated root GPU device id

    Raises:
        TypeError:
            If ``gpus`` is not a list
        AssertionError:
            If GPU list is empty
    """
    if gpus is None:
        return None

    if not isinstance(gpus, list):
        raise TypeError("GPUs should be a list")

    assert len(gpus) > 0, "GPUs should be a non-empty list"

    # set root gpu
    return gpus[0]


def _parse_gpu_ids(
    gpus: Optional[Union[int, str, list[int]]],
    include_cuda: bool = False,
    include_mps: bool = False,
) -> Optional[list[int]]:
    """Parses the GPU IDs given in the format as accepted by the :class:`~lightning.pytorch.trainer.trainer.Trainer`.

    Args:
        gpus: An int -1 or string '-1' indicate that all available GPUs should be used.
            A list of unique ints or a string containing a list of comma separated unique integers
            indicates specific GPUs to use.

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Call the public entry point `parse_devices(...)` (or `_parse_gpu_ids`) instead of `_determine_root_gpu_device` directly, so input is normalized.
2. If you must call it, normalize first: pass `gpus` as a list (e.g. `[0]`) or None.
3. Convert Trainer-style specs yourself: int n -> list(range(n)); '2' -> [0,1]; '-1' -> all available GPU indices.

Example fix

# before
root = _determine_root_gpu_device(gpus=1)  # TypeError

# after
root = _determine_root_gpu_device(gpus=[0])

assert gpus is None or (isinstance(gpus, list) and len(gpus) > 0)
root_gpu = _determine_root_gpu_device(gpus)

def is_gpu_list(v) -> bool:
    return v is None or (isinstance(v, list) and len(v) > 0 and all(isinstance(i, int) for i in v))

When it happens

Trigger: Calling `lightning.fabric.utilities.device_parser._determine_root_gpu_device` directly with a non-list such as `gpus=1` or `gpus='0,1'` instead of a list like `[0]`, instead of going through `parse_devices`/`_parse_gpu_ids` which normalize input first.

Common situations: User code or tests bypassing the public device-resolution API and calling the internal helper with the raw Trainer-style `gpus` argument (int, string, or None-like sentinel).

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• str(_TRANSFORMER_ENGINE_AVAILABLE)
• GPUs requested but none are available.
• __setitem__ is not supported
• No supported gpu backend found!
• Device should be CPU, got {device} instead.

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/02b29811b70d19e3. Report an issue: GitHub.