Lightning-AI/pytorch-lightning · error · MisconfigurationException

Trying to inject custom `Sampler` into the `{dataloader_cls_

Error message

Trying to inject custom `Sampler` into the `{dataloader_cls_name}` instance. This would fail as some of the `__init__` arguments are not available as instance attributes. The missing attributes are {sorted_required_args}. If you instantiate your `{dataloader_cls_name}` inside a `*_dataloader` hook of your module, we will do this for you. Otherwise, define {missing_args_message} inside your `__init__`.

What it means

When Lightning re-creates a dataloader to inject a custom (distributed) sampler, it inspects the DataLoader.__init__ signature and reads each required argument from instance attributes of the same name. If some required init args (beyond dataset) are not stored as self.<arg> attributes — typical of custom __init__ overrides that rename or don't persist args — reconstruction is impossible and this MisconfigurationException is raised. Defining the attributes or constructing the loader inside a *_dataloader hook (where Lightning saves the original args) resolves it.

Source

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

        dl_kwargs["batch_sampler"] = None
        dl_kwargs["sampler"] = None
    else:
        dl_kwargs.update(_dataloader_init_kwargs_resolve_sampler(dataloader, sampler))

    required_args = {
        p.name
        for p in params.values()
        if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
        and p.default is p.empty
        and p.name not in dl_kwargs
        and p.name not in arg_names
    }
    # the dataloader has required args which we could not extract from the existing attributes
    if required_args:
        sorted_required_args = sorted(required_args)
        dataloader_cls_name = dataloader.__class__.__name__
        missing_args_message = ", ".join(f"`self.{arg_name}`" for arg_name in sorted_required_args)
        raise MisconfigurationException(
            f"Trying to inject custom `Sampler` into the `{dataloader_cls_name}` instance. "
            "This would fail as some of the `__init__` arguments are not available as instance attributes. "
            f"The missing attributes are {sorted_required_args}. If you instantiate your `{dataloader_cls_name}` "
            "inside a `*_dataloader` hook of your module, we will do this for you."
            f" Otherwise, define {missing_args_message} inside your `__init__`."
        )

    if not has_variadic_kwargs:
        # the dataloader signature does not allow keyword arguments that need to be passed
        missing_kwargs = (set(dl_kwargs) | set(arg_names)) - params.keys()
        if missing_kwargs:
            sorted_missing_kwargs = sorted(missing_kwargs)
            dataloader_cls_name = dataloader.__class__.__name__
            raise TypeError(
                f"Trying to inject parameters into the `{dataloader_cls_name}` instance. "
                "This would fail as it doesn't expose all its attributes in the `__init__` signature. "
                f"The missing arguments are {sorted_missing_kwargs}. HINT: If you wrote the `{dataloader_cls_name}` "
                "class, add the `__init__` arguments or allow passing `**kwargs`"

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. In your custom DataLoader.__init__, store every init argument as a same-named attribute: self.batch_size = batch_size, etc.
2. Or instantiate the loader inside a train_dataloader()/val_dataloader() hook so Lightning captures __pl_saved_args for you
3. Alternatively pre-configure a sampler manually and avoid Lightning's automatic sampler injection (e.g. pass a loader Lightning doesn't need to rewrap)

Example fix

# before
class MyLoader(DataLoader):
    def __init__(self, dataset, batch_size):
        super().__init__(dataset, batch_size=batch_size)
        self.bs = batch_size  # renamed -> not discoverable

# after
class MyLoader(DataLoader):
    def __init__(self, dataset, batch_size):
        super().__init__(dataset, batch_size=batch_size)
        self.batch_size = batch_size  # attribute name matches init arg

import inspect
from torch.utils.data import DataLoader
missing = [p for p in inspect.signature(MyLoader.__init__).parameters
           if p not in ('self', 'dataset', 'args', 'kwargs') and not hasattr(loader, p)]
assert not missing, f'store init args as attributes: {missing}'

When it happens

Trigger: A custom DataLoader subclass whose __init__ has required args (e.g. batch_sampler, collate_fn positional) that are not set as identically-named instance attributes, then passing an instance through a path that injects a sampler (fabric.setup_dataloaders / Trainer with distributed strategy).

Common situations: Custom loader subclasses that consume args without assigning self.<arg>; third-party loaders with non-standard attribute naming; upgrading Lightning/torch where sampler injection becomes required in distributed training.

Related errors

• The dataloader {dataloader} needs to subclass `torch.utils.d
• Trying to inject parameters into the `{dataloader_cls_name}`
• You seem to have configured a sampler in your DataLoader whi
• You seem to have configured a sampler in your DataLoader whi
• "You cannot pass `train_dataloader` or `val_dataloaders` to

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