{"record":{"id":"6bcb9119ae4095c5","repo":"Lightning-AI/pytorch-lightning","slug":"dataloader-cls-name-within-local-rank-has-zero","errorCode":null,"errorMessage":"`{dataloader_cls_name}` within local rank has zero length. Please make sure that it returns at least 1 batch.","messagePattern":"`(.+?)` within local rank has zero length\\. Please make sure that it returns at least 1 batch\\.","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/utilities/data.py","lineNumber":113,"sourceCode":"    strategy: \"pl.strategies.Strategy\",\n    allow_zero_length_dataloader_with_multiple_devices: bool = False,\n) -> TypeGuard[Sized]:\n    \"\"\"Checks if a given object has ``__len__`` method implemented on all ranks.\"\"\"\n    local_length = sized_len(dataloader)\n    if local_length is None:\n        # __len__ is not defined, skip these checks\n        return False\n\n    total_length = strategy.reduce(torch.tensor(local_length, device=strategy.root_device), reduce_op=\"sum\")\n    if total_length == 0:\n        rank_zero_warn(\n            f\"Total length of `{type(dataloader).__name__}` across ranks is zero.\"\n            \" Please make sure this was your intention.\"\n        )\n    if total_length > 0 and local_length == 0:\n        dataloader_cls_name = type(dataloader).__name__\n        if not allow_zero_length_dataloader_with_multiple_devices:\n            raise RuntimeError(\n                f\"`{dataloader_cls_name}` within local rank has zero length.\"\n                \" Please make sure that it returns at least 1 batch.\"\n            )\n        rank_zero_warn(\n            f\"Total length of `{dataloader_cls_name}` across ranks is zero, but local rank has zero\"\n            \" length. Please be cautious of uneven batch length.\"\n        )\n\n    if has_iterable_dataset(dataloader):\n        rank_zero_warn(\n            \"Your `IterableDataset` has `__len__` defined.\"\n            \" In combination with multi-process data loading (when num_workers > 1),\"\n            \" `__len__` could be inaccurate if each worker is not configured independently\"\n            \" to avoid having duplicate data.\"\n        )\n    return True\n\n","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/utilities/data.py#L95-L131","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the dataset has at least one batch per rank (increase dataset size or drop_last=False with pad-to-multiple sharding)","Fix the sampler so every rank gets at least one sample (e.g. DistributedSampler(drop_last=False) pads across ranks)","If a zero-length local dataloader is intentional, opt in: Trainer(allow_zero_length_dataloader_with_multiple_devices=True)"],"exampleFix":"# before\nsampler = DistributedSampler(dataset, drop_last=True)  # with tiny dataset\n\n# after\nsampler = DistributedSampler(dataset, drop_last=False)  # pads so every rank gets data","handlingStrategy":"validation","validationCode":"length = len(dataloader)  # local rank\nassert length > 0 or trainer.allow_zero_length_dataloader_with_multiple_devices, 'local rank dataloader is empty'","typeGuard":null,"tryCatchPattern":"from lightning.pytorch.utilities.exceptions import MisconfigurationException\ntry:\n    trainer.fit(model)\nexcept (RuntimeError, MisconfigurationException) as e:\n    if 'zero length' in str(e):\n        raise SystemExit('dataset too small for world size; reduce devices or enlarge dataset')\n    raise","preventionTips":["Check len(dataset) >= world_size so DistributedSampler can give every rank at least one sample","Use DistributedSampler(drop_last=False) which pads across ranks","Only enable allow_zero_length_dataloader_with_multiple_devices when empty ranks are truly acceptable"],"tags":["pytorch-lightning","dataloader","distributed-training","empty-dataset"],"backgroundTag":"distributed-dataloader-empty-rank","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}