{"record":{"id":"eafb56023baeeaa0","repo":"Lightning-AI/pytorch-lightning","slug":"lightning-can-t-inject-a-distributed-sampler-in-eafb56","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 `Trainer(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 `Trainer\\(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/pytorch/utilities/data.py","lineNumber":317,"sourceCode":"                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` and\"\n                    \" instantiate your custom batch sampler inside the `*_dataloader` hook of your module,\"\n                    \" or set `Trainer(use_distributed_sampler=False)`. If you choose the latter, you will be\"\n                    \" responsible for handling the distributed sampling within your batch sampler.\"\n                ) from ex\n        elif is_predicting:\n            rank_zero_warn(\n                f\"You are using a custom batch sampler `{batch_sampler_cls.__qualname__}` for prediction.\"\n                \" Lightning would normally set `drop_last=False` to ensure all samples are returned, but for\"\n                \" custom samplers it can't guarantee this. Make sure your sampler is configured correctly to return\"\n                \" all indices.\",\n                category=PossibleUserWarning,\n            )\n        else:\n            # The sampler is not a PyTorch `BatchSampler`, we don't know how to inject a custom sampler or\n            # how to adjust the `drop_last` value\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 `Trainer(use_distributed_sampler=False)`. If you choose the latter, you will be\"\n                \" responsible for handling the distributed sampling within your batch sampler.\"\n            )\n\n        if is_predicting:\n            batch_sampler = _IndexBatchSamplerWrapper(batch_sampler)\n\n        # batch_sampler option is mutually exclusive with batch_size, shuffle, sampler, and drop_last\n        return {\n            \"sampler\": None,\n            \"shuffle\": False,\n            \"batch_sampler\": batch_sampler,\n            \"batch_size\": 1,\n            \"drop_last\": False,\n        }\n","sourceCodeStart":299,"sourceCodeEnd":335,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/utilities/data.py#L299-L335","documentation":"Raised as a TypeError when the DataLoader's batch_sampler object is not a PyTorch BatchSampler at all, so Lightning has no mechanism to inject a distributed sampler or adjust drop_last. This is the 'we don't know how to touch this' branch of sampler replacement: unlike 626 there is no prior exception; the object simply fails an isinstance/duck-type check.","triggerScenarios":"Passing an arbitrary object as DataLoader(batch_sampler=...) that does not follow the BatchSampler API, during distributed sampler replacement triggered by DDP/FSDP-style strategies.","commonSituations":"Custom iterable batch samplers or generator-based samplers; single-device code moved to multi-GPU; mock/test objects used as batch samplers.","solutions":["Subclass torch.utils.data.sampler.BatchSampler so Lightning can re-instantiate it","Or set Trainer(use_distributed_sampler=False) and handle sharding across ranks inside your sampler"],"exampleFix":"# before\nloader = DataLoader(dataset, batch_sampler=MyCustomIterable())\n\n# after\nloader = DataLoader(dataset, batch_sampler=MyBatchSampler(sampler, batch_size=32, drop_last=False))","handlingStrategy":"type-guard","validationCode":"from torch.utils.data import BatchSampler, DataLoader\nassert isinstance(loader, DataLoader) and (loader.batch_sampler is None or isinstance(loader.batch_sampler, BatchSampler))","typeGuard":"from torch.utils.data import BatchSampler\nfrom typing import Any\n\ndef batch_sampler_is_supported(obj: Any) -> bool:\n    return obj is None or isinstance(obj, BatchSampler)","tryCatchPattern":null,"preventionTips":["Never pass ad-hoc iterables as batch_sampler in distributed runs","Keep a lint/unit check that dataloaders returned from hooks use standard or BatchSampler-compatible components","Document that custom batch samplers require use_distributed_sampler=False"],"tags":["pytorch-lightning","batch-sampler","distributed-training","typeerror"],"backgroundTag":"custom-batch-sampler-injection-failed","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}