Lightning-AI/pytorch-lightning · error · RuntimeError

`{dataloader_cls_name}` within local rank has zero length. P

Error message

`{dataloader_cls_name}` within local rank has zero length. Please make sure that it returns at least 1 batch.

What it means

Raised by has_len_all_ranks when the combined dataloader length across all ranks is positive but the local rank's dataloader has length 0. This means other ranks will process batches while this rank does nothing, which usually indicates a misconfigured distributed sampler or sharding that assigned no data to this rank. Lightning refuses to proceed unless you explicitly allowed zero-length dataloaders with allow_zero_length_dataloader_with_multiple_devices=True.

Source

Thrown at src/lightning/pytorch/utilities/data.py:113

    strategy: "pl.strategies.Strategy",
    allow_zero_length_dataloader_with_multiple_devices: bool = False,
) -> TypeGuard[Sized]:
    """Checks if a given object has ``__len__`` method implemented on all ranks."""
    local_length = sized_len(dataloader)
    if local_length is None:
        # __len__ is not defined, skip these checks
        return False

    total_length = strategy.reduce(torch.tensor(local_length, device=strategy.root_device), reduce_op="sum")
    if total_length == 0:
        rank_zero_warn(
            f"Total length of `{type(dataloader).__name__}` across ranks is zero."
            " Please make sure this was your intention."
        )
    if total_length > 0 and local_length == 0:
        dataloader_cls_name = type(dataloader).__name__
        if not allow_zero_length_dataloader_with_multiple_devices:
            raise RuntimeError(
                f"`{dataloader_cls_name}` within local rank has zero length."
                " Please make sure that it returns at least 1 batch."
            )
        rank_zero_warn(
            f"Total length of `{dataloader_cls_name}` across ranks is zero, but local rank has zero"
            " length. Please be cautious of uneven batch length."
        )

    if has_iterable_dataset(dataloader):
        rank_zero_warn(
            "Your `IterableDataset` has `__len__` defined."
            " In combination with multi-process data loading (when num_workers > 1),"
            " `__len__` could be inaccurate if each worker is not configured independently"
            " to avoid having duplicate data."
        )
    return True

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Ensure the dataset has at least one batch per rank (increase dataset size or drop_last=False with pad-to-multiple sharding)
2. Fix the sampler so every rank gets at least one sample (e.g. DistributedSampler(drop_last=False) pads across ranks)
3. If a zero-length local dataloader is intentional, opt in: Trainer(allow_zero_length_dataloader_with_multiple_devices=True)

Example fix

# before
sampler = DistributedSampler(dataset, drop_last=True)  # with tiny dataset

# after
sampler = DistributedSampler(dataset, drop_last=False)  # pads so every rank gets data

length = len(dataloader)  # local rank
assert length > 0 or trainer.allow_zero_length_dataloader_with_multiple_devices, 'local rank dataloader is empty'

from lightning.pytorch.utilities.exceptions import MisconfigurationException
try:
    trainer.fit(model)
except (RuntimeError, MisconfigurationException) as e:
    if 'zero length' in str(e):
        raise SystemExit('dataset too small for world size; reduce devices or enlarge dataset')
    raise

When it happens

Trigger: Running distributed training (DDP etc.) where Trainer(allow_zero_length_dataloader_with_multiple_devices=False) (default) and a dataloader whose __len__ on this rank is 0 while the total across ranks is > 0; e.g. a DistributedSampler with more ranks than samples, or per-rank sharding that gives one rank no data.

Common situations: World size exceeds dataset size (tiny dataset, many GPUs); uneven manual sharding by rank; debugging with limit_val_batches or synthetic empty dataloaders; using a sampler that filters all data on one rank.

Related errors

• `setup_dataloaders` requires at least one dataloader as inpu
• A dataloader should be passed only once to the `setup_datalo
• Only PyTorch DataLoader are currently supported in `setup_da
• Trying to inject parameters into the `{dataloader_cls_name}`
• The {constructor.__name__} implementation has an error where

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