{"record":{"id":"869729e13b8c2b42","repo":"Lightning-AI/pytorch-lightning","slug":"lightning-can-t-inject-a-distributed-sampler-in","errorCode":null,"errorMessage":" Lightning can't inject a (distributed) sampler into your batch sampler, because it doesn't subclass PyTorch's `BatchSampler`. To mitigate this, either follow the API of `BatchSampler` or set`.setup_dataloaders(..., use_distributed_sampler=False)`. If you choose the latter, you will be responsible for handling the distributed sampling within your batch sampler.","messagePattern":" Lightning can't inject a \\(distributed\\) sampler into your batch sampler, because it doesn't subclass PyTorch's `BatchSampler`\\. To mitigate this, either follow the API of `BatchSampler` or set`\\.setup_dataloaders\\(\\.\\.\\., use_distributed_sampler=False\\)`\\. If you choose the latter, you will be responsible for handling the distributed sampling within your batch sampler\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/utilities/data.py","lineNumber":220,"sourceCode":"            # This is a sampler for which we could not capture the init args, but it kinda looks like a batch sampler\n            # even if it does not inherit from PyTorch's interface.\n            try:\n                batch_sampler = batch_sampler_cls(\n                    sampler,\n                    batch_size=batch_sampler.batch_size,\n                    drop_last=batch_sampler.drop_last,\n                )\n            except TypeError as ex:\n                import re\n\n                match = re.match(r\".*__init__\\(\\) (got multiple values)|(missing \\d required)\", str(ex))\n                if not match:\n                    # an unexpected `TypeError`, continue failure\n                    raise\n\n                # There could either be too few or too many arguments. Customizing the message based on this doesn't\n                # make much sense since our MisconfigurationException is going to be raised from the original one.\n                raise TypeError(\n                    \" Lightning can't inject a (distributed) sampler into your batch sampler, because it doesn't\"\n                    \" subclass PyTorch's `BatchSampler`. To mitigate this, either follow the API of `BatchSampler`\"\n                    \" or set`.setup_dataloaders(..., use_distributed_sampler=False)`. If you choose the latter, you\"\n                    \" will be responsible for handling the distributed sampling within your batch sampler.\"\n                ) from ex\n        else:\n            # The sampler is not a PyTorch `BatchSampler`, we don't know how to inject a custom sampler\n            raise TypeError(\n                \" Lightning can't inject a (distributed) sampler into your batch sampler, because it doesn't\"\n                \" subclass PyTorch's `BatchSampler`. To mitigate this, either follow the API of `BatchSampler`\"\n                \" or set`.setup_dataloaders(..., use_distributed_sampler=False)`. If you choose the latter, you\"\n                \" will be responsible for handling the distributed sampling within your batch sampler.\"\n            )\n\n        return {\n            \"sampler\": None,\n            \"shuffle\": False,\n            \"batch_sampler\": batch_sampler,","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/utilities/data.py#L202-L238","documentation":"Lightning attempted to re-instantiate a custom batch sampler to swap in a distributed sampler by calling it with the same signature as PyTorch's `BatchSampler.__init__(sampler, batch_size, drop_last, ...)`. The call raised a TypeError indicating the class doesn't follow that API (it isn't a `BatchSampler` subclass), so Lightning cannot inject the sampler and re-raises with guidance.","triggerScenarios":"A DataLoader with a `batch_sampler` that is not a subclass of `torch.utils.data.BatchSampler` is passed to Fabric's `setup_dataloaders` while distributed sampling is enabled; Lightning tries `type(batch_sampler)(sampler=..., batch_size=..., drop_last=...)` and the constructor rejects those arguments.","commonSituations":"Custom iterable batch sampler classes (e.g. grouping buckets, weighted batch samplers) used with multi-GPU DDP training in Lightning Fabric.","solutions":["Set `use_distributed_sampler=False` in `setup_dataloaders(...)` and implement distributed sharding inside your batch sampler yourself.","Refactor your custom class to subclass `torch.utils.data.BatchSampler` and follow its `__init__(sampler, batch_size, drop_last)` API.","Use a regular `sampler=` DataLoader instead of `batch_sampler=` so Lightning can wrap it with a DistributedSampler."],"exampleFix":"# before\nloader = DataLoader(dataset, batch_sampler=MyCustomBatchSampler(...))\nfabric.setup_dataloaders(loader)\n\n# after\nloader = DataLoader(dataset, batch_sampler=MyCustomBatchSampler(...))\nfabric.setup_dataloaders(loader, use_distributed_sampler=False)","handlingStrategy":"fallback","validationCode":"from torch.utils.data import BatchSampler\n\ndef is_standard_batch_sampler(bs) -> bool:\n    return isinstance(bs, BatchSampler)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Subclass torch.utils.data.BatchSampler for custom batch samplers used with Lightning.","Otherwise always pass use_distributed_sampler=False and shard inside your sampler via fabric/world info."],"tags":["pytorch-lightning","batch-sampler","distributed-sampler","ddp"],"backgroundTag":"sampler-injection-unsupported","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}