Lightning-AI/pytorch-lightning · error · ValueError

The dataloader {dataloader} needs to subclass `torch.utils.d

Error message

The dataloader {dataloader} needs to subclass `torch.utils.data.DataLoader`

What it means

Lightning's _update_dataloader/_get_dataloader_init_args_and_kwargs rebuilds a dataloader with a new distributed sampler by re-playing its __init__ arguments, which requires the object to be an instance of torch.utils.data.DataLoader. Custom or third-party dataloader classes that don't subclass DataLoader (e.g. some graph/point-cloud libraries, HF-specific iterables) cannot be re-constructed this way.

Source

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

            "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 length is not None


def _update_dataloader(dataloader: DataLoader, sampler: Union[Sampler, Iterable]) -> DataLoader:
    dl_args, dl_kwargs = _get_dataloader_init_args_and_kwargs(dataloader, sampler)
    return _reinstantiate_wrapped_cls(dataloader, *dl_args, **dl_kwargs)


def _get_dataloader_init_args_and_kwargs(
    dataloader: DataLoader,
    sampler: Union[Sampler, Iterable],
) -> tuple[tuple[Any], dict[str, Any]]:
    if not isinstance(dataloader, DataLoader):
        raise ValueError(f"The dataloader {dataloader} needs to subclass `torch.utils.data.DataLoader`")

    was_wrapped = hasattr(dataloader, "__pl_saved_args")
    if was_wrapped:
        dl_args = dataloader.__pl_saved_args
        dl_kwargs = dataloader.__pl_saved_kwargs
        arg_names = dataloader.__pl_saved_arg_names
        original_dataset = dataloader.__dataset  # we have this saved from _wrap_init
    else:
        # get the dataloader instance attributes
        attrs = {k: v for k, v in vars(dataloader).items() if not k.startswith("_")}
        # We cannot be 100% sure the class sets dataset argument. Let's set it to None to be safe
        # and hope we can get it from the instance attributes
        original_dataset = None
        # not part of `vars`
        attrs["multiprocessing_context"] = dataloader.multiprocessing_context
        arg_names = ()

    # get the dataloader instance `__init__` parameters

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Subclass torch.utils.data.DataLoader in your custom loader so Lightning can replay its init args
2. Wrap your dataset/batch iterator in a standard torch DataLoader instead of a bespoke loader class
3. If the object only supports iteration, provide the sampler logic yourself and avoid paths that require re-wrapping (e.g. don't pass it through fabric.setup_dataloaders)

Example fix

# before
class MyLoader:  # not a DataLoader
    def __init__(self, data): ...

# after
from torch.utils.data import DataLoader
class MyLoader(DataLoader):
    def __init__(self, data, **kwargs):
        super().__init__(dataset=MyDataset(data), **kwargs)

from torch.utils.data import DataLoader
assert isinstance(loader, DataLoader), 'pass a torch.utils.data.DataLoader subclass to setup_dataloaders'

from torch.utils.data import DataLoader

def is_torch_dataloader(obj) -> bool:
    return isinstance(obj, DataLoader)

When it happens

Trigger: Passing a non-DataLoader iterable (custom loader class, library-specific loader like some PyG variants) into a distributed Fabric/Lightning setup where Lightning calls _update_dataloader to inject a DistributedSampler; e.g. fabric.setup_dataloaders(loader).

Common situations: Wrapping exotic loader classes from domain libraries; passing DataChunk/Iterable wrappers; versions of libraries that changed loader base classes.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Trying to inject custom `Sampler` into the `{dataloader_cls_
• `activation_checkpointing_policy` must be a set, found {poli
• Blocking backward sync is only possible if the module passed
• Trying to inject parameters into the `{dataloader_cls_name}`
• You seem to have configured a sampler in your DataLoader whi

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