Lightning-AI/pytorch-lightning · error · MisconfigurationException

f"You requested to check {limit_batches} of the `{stage.data

Error message

f"You requested to check {limit_batches} of the `{stage.dataloader_prefix}_dataloader` but" f" {limit_batches} * {length} < 1. Please increase the" f" `limit_{stage.dataloader_prefix}_batches` argument. Try at least" f" `limit_{stage.dataloader_prefix}_batches={min_percentage}`"

What it means

After applying a fractional limit_batches to a finite dataloader length, the computed number of batches rounds down to zero while the user requested a positive fraction. Lightning raises this MisconfigurationException because zero batches means the stage would silently do nothing, which is almost never intended.

Source

Thrown at src/lightning/pytorch/trainer/connectors/data_connector.py:469

) -> Union[int, float]:
    if length == 0:
        return int(length)

    num_batches = length
    # limit num batches either as a percent or num steps
    if isinstance(limit_batches, int):
        num_batches = min(length, limit_batches)
    elif isinstance(limit_batches, float) and length != float("inf"):
        num_batches = int(length * limit_batches)
    elif limit_batches != 1.0:
        raise MisconfigurationException(
            f"When using an `IterableDataset`, `Trainer(limit_{stage.dataloader_prefix}_batches)` must be"
            f" `1.0` or an int. An int specifies `num_{stage.dataloader_prefix}_batches` to use."
        )

    if num_batches == 0 and limit_batches > 0.0 and isinstance(limit_batches, float) and length != float("inf"):
        min_percentage = 1.0 / length
        raise MisconfigurationException(
            f"You requested to check {limit_batches} of the `{stage.dataloader_prefix}_dataloader` but"
            f" {limit_batches} * {length} < 1. Please increase the"
            f" `limit_{stage.dataloader_prefix}_batches` argument. Try at least"
            f" `limit_{stage.dataloader_prefix}_batches={min_percentage}`"
        )
    return num_batches


def _process_dataloader(
    trainer: "pl.Trainer", trainer_fn: TrainerFn, stage: RunningStage, dataloader: object
) -> object:
    if stage != RunningStage.TRAINING:
        is_shuffled = _is_dataloader_shuffled(dataloader)
        # limit this warning only for samplers assigned automatically when shuffle is set
        if is_shuffled:
            rank_zero_warn(
                f"Your `{stage.dataloader_prefix}_dataloader`'s sampler has shuffling enabled,"
                " it is strongly recommended that you turn shuffling off for val/test dataloaders.",

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Increase limit_batches to at least the suggested min_percentage (1/length), e.g. limit_val_batches=0.3 for length 3
2. Use an integer count instead of a percentage: Trainer(limit_val_batches=1)
3. Enlarge the dataloader length (larger val set or smaller batch_size) so the fraction yields >=1 batch

Example fix

# before (length=5 val dataloader)
trainer = Trainer(limit_val_batches=0.1)  # 0.1*5 = 0 batches

# after
trainer = Trainer(limit_val_batches=1)  # int count
# or
trainer = Trainer(limit_val_batches=0.4)

length = len(dl)  # dataloader length
if isinstance(limit_batches, float) and limit_batches > 0 and int(length * limit_batches) == 0:
    raise ValueError(f"limit_batches too small for length={length}; need >= {1.0/length}")

def is_valid_fraction(limit_batches: float, length: int) -> bool:
    return int(length * limit_batches) >= 1

When it happens

Trigger: _parse_num_batches computes int(length * limit_batches) == 0 while limit_batches > 0.0 and length is finite, e.g. limit_val_batches=0.1 with a val dataloader of length 5 (0.1*5 = 0.5 -> 0); limit_test_batches=0.25 with 2 batches.

Common situations: Using percentage-based limit_val_batches (the Trainer default is 1.0 but users often set 0.1 or 0.25) with a small validation set; sanity-check configs with tiny datasets; unit tests with 1-2 batches per epoch.

Related errors

• f"When using an `IterableDataset`, `Trainer(limit_{stage.dat
• Device should be CPU, got {device} instead.
• You requested to find {num_devices} devices but there are no
• You are trying to `self.log()` but the loop's result collect
• You are trying to `self.log()` but it is not managed by the

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