Lightning-AI/pytorch-lightning · critical · MisconfigurationException

`val_dataloader` must be implemented to be used with the Lig

Error message

`val_dataloader` must be implemented to be used with the Lightning Trainer

What it means

LightningModule.val_dataloader is a stub hook that raises MisconfigurationException unless the user overrides it. The Trainer requires a validation dataloader whenever a validation loop runs (trainer.fit with validation, trainer.validate). If the method is not implemented on your subclass, calling it produces this error.

Source

Thrown at src/lightning/pytorch/core/hooks.py:540

a positive integer.

It's recommended that all data downloads and preparation happen in :meth:`prepare_data`.

- :meth:`~lightning.pytorch.trainer.trainer.Trainer.fit`
- :meth:`~lightning.pytorch.trainer.trainer.Trainer.validate`
- :meth:`prepare_data`
- :meth:`setup`

Note:
Lightning tries to add the correct sampler for distributed and arbitrary hardware
There is no need to set it yourself.

Note:
If you don't need a validation dataset and a :meth:`validation_step`, you don't need to
implement this method.

"""
raise MisconfigurationException("`val_dataloader` must be implemented to be used with the Lightning Trainer")

def predict_dataloader(self) -> EVAL_DATALOADERS:
r"""An iterable or collection of iterables specifying prediction samples.

For more information about multiple dataloaders, see this :ref:`section <multiple-dataloaders>`.

It's recommended that all data downloads and preparation happen in :meth:`prepare_data`.

- :meth:`~lightning.pytorch.trainer.trainer.Trainer.predict`
- :meth:`prepare_data`
- :meth:`setup`

Note:
Lightning tries to add the correct sampler for distributed and arbitrary hardware
There is no need to set it yourself.

Return:
A :class:`torch.utils.data.DataLoader` or a sequence of them specifying prediction samples.

View on GitHub (pinned to 9fed5c27d2)

Solutions

Implement `def val_dataloader(self)` in your LightningModule returning a DataLoader or sequence of DataLoaders
If you don't need validation, call trainer.fit(model) without a val_dataloader or use trainer.validate only when implemented
For prediction-only workflows use trainer.predict with predict_dataloader instead

Example fix

// before
class MyModel(L.LightningModule):
    def training_step(self, batch, batch_idx): ...
    # no val_dataloader

# after
class MyModel(L.LightningModule):
    def training_step(self, batch, batch_idx): ...
    def val_dataloader(self):
        return DataLoader(val_dataset, batch_size=32)

Defensive patterns

Strategy: validation

Validate before calling

hook = getattr(model, 'val_dataloader', None)
implemented = hook is not None and type(model).val_dataloader is not L.LightningModule.val_dataloader
if not implemented and need_validation:
    raise ValueError('implement val_dataloader before trainer.validate/fit')

Type guard

def has_val_dataloader(model) -> bool:
    return type(model).val_dataloader is not L.LightningModule.val_dataloader

Try / catch

from lightning.pytorch.utilities.exceptions import MisconfigurationException
try:
    trainer.validate(model)
except MisconfigurationException as e:
    if 'val_dataloader' in str(e):
        model.val_dataloader = lambda: DataLoader(val_ds)

Prevention

Always pair validation_step with val_dataloader in module templates
Run a smoke test trainer.fit(..., max_steps=1, limit_val_batches=1) in CI to catch missing hooks

When it happens

Trigger: Calling trainer.validate(model) or trainer.fit(model) with a validation loop enabled on a LightningModule that does not override val_dataloader; or calling model.val_dataloader() directly.

Common situations: User wrote training_step but forgot the validation dataloader; copied a template module that only implements train_dataloader; assumed the Trainer would fall back to train_dataloader for validation.

Related errors

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