Lightning-AI/pytorch-lightning · error · ValueError

`local_world_size` should be >= 1, got {local_world_size}.

Error message

`local_world_size` should be >= 1, got {local_world_size}.

What it means

`lightning.fabric.utilities.data.suggested_max_num_workers` validates its `local_world_size` argument (number of processes/devices on the current machine) and rejects values below 1, since a non-positive process count is meaningless for computing the suggested worker count `max(1, cpu_count // local_world_size - 1)`.

Source

Thrown at src/lightning/fabric/utilities/data.py:453

    ) is not None:
        objects[id(sampler)] = sampler
    for obj in objects.values():
        set_epoch = getattr(obj, "set_epoch", None)
        if callable(set_epoch):
            set_epoch(epoch)


def suggested_max_num_workers(local_world_size: int) -> int:
    """Suggests an upper bound of ``num_workers`` to use in a PyTorch :class:`~torch.utils.data.DataLoader` based on
    the number of CPU cores available on the system and the number of distributed processes in the current machine.

    Args:
        local_world_size: The number of distributed processes running on the current machine. Set this to the number
            of devices configured in Fabric/Trainer.

    """
    if local_world_size < 1:
        raise ValueError(f"`local_world_size` should be >= 1, got {local_world_size}.")
    cpu_count = _num_cpus_available()
    return max(1, cpu_count // local_world_size - 1)  # -1 to leave some resources for main process


def _num_cpus_available() -> int:
    if hasattr(os, "sched_getaffinity"):
        return len(os.sched_getaffinity(0))

    cpu_count = os.cpu_count()
    return 1 if cpu_count is None else cpu_count


class AttributeDict(dict):
    """A container to store state variables of your program.

    This is a drop-in replacement for a Python dictionary, with the additional functionality to access and modify keys
    through attribute lookup for convenience.

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Ensure the value passed is >= 1 — typically the number of devices/processes per node (e.g. `len(fabric.device_ids)` or torch.distributed.get_world_size() // num_nodes).
2. Validate/initialize the variable holding local_world_size before the call (guard against 0/None defaults).
3. If computing from a devices list, check it is non-empty first.

Example fix

# before
workers = suggested_max_num_workers(local_world_size=num_local_procs)  # 0 when unset

# after
num_local_procs = num_local_procs or 1
workers = suggested_max_num_workers(local_world_size=num_local_procs)

local_world_size = max(1, int(local_world_size or 0))
workers = suggested_max_num_workers(local_world_size=local_world_size)

def is_valid_world_size(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 1

When it happens

Trigger: Calling `suggested_max_num_workers(local_world_size=0)` or a negative value, e.g. by passing an uninitialized device count, `len(devices)` where devices is empty, or a variable computed before it was assigned.

Common situations: Scripts computing world size from CLI args or environment before validation (default 0), or passing a numpy/None-derived value; also unit tests of the helper itself.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Device should be CUDA, got {device} instead.
• You requested to find {num_devices} devices but there are no
• `setup_optimizers` requires at least one optimizer as input.
• `setup_dataloaders` requires at least one dataloader as inpu
• Passed `{type(self).__name__}(precision={precision!r})`. Pre

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