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

Raised as a MisconfigurationException when Lightning tries to inject a custom (distributed) Sampler into a DataLoader subclass but cannot reconstruct it: the subclass's __init__ has required arguments that Lightning cannot recover from the instance's attributes. Lightning reconstructs dataloaders by reading init args back from instance attributes (e.g. self.batch_size), so required init params without matching attributes are unrecoverable.

Source

Thrown at src/lightning/pytorch/utilities/data.py:209

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

    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 MisconfigurationException(
                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

Store every required __init__ argument as an identically named instance attribute: def __init__(self, my_flag): super().__init__(...); self.my_flag = my_flag
Give the required parameters defaults so they are not required
Instantiate the dataloader inside the *_dataloader hook so Lightning saves the original args

Example fix

# before
class MyDL(DataLoader):
    def __init__(self, dataset, mode):
        super().__init__(dataset, batch_size=2 if mode == 'train' else 1)

# after
class MyDL(DataLoader):
    def __init__(self, dataset, mode):
        self.mode = mode  # attribute matching the init arg name
        super().__init__(dataset, batch_size=2 if mode == 'train' else 1)

Defensive patterns

Strategy: validation

Validate before calling

import inspect
from torch.utils.data import DataLoader

def validate_dataloader_attrs(dl: DataLoader) -> None:
    sig = inspect.signature(type(dl).__init__)
    params = inspect.signature(DataLoader.__init__).parameters
    for name in sig.parameters:
        if name in ('self',) or name in params:
            continue
        assert hasattr(dl, name), f'{type(dl).__name__} must store self.{name}'

Prevention

Store every __init__ arg as self.<argname> in custom DataLoader subclasses
Give custom init parameters default values where possible
Instantiate custom dataloaders inside the *_dataloader hooks so Lightning records the original args

When it happens

Trigger: Returning a DataLoader subclass with required __init__ parameters (other than the standard set) that are not stored as same-named instance attributes, from a *_dataloader hook during distributed training; e.g. def __init__(self, my_flag): ... without self.my_flag = my_flag.

Common situations: Custom DataLoader subclasses that rename or compute init args instead of storing them verbatim; changing a subclass's signature after Lightning worked before; distributed runs only (single device may not re-instantiate).

Related errors

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