Lightning-AI/pytorch-lightning · error · ValueError

`prefetch_batches` should at least be 0.

Error message

`prefetch_batches` should at least be 0.

What it means

_PrefetchDataFetcher.__init__ validates that prefetch_batches >= 0; a negative value raises ValueError immediately since negative prefetching is meaningless and would break the buffering logic.

Source

Thrown at src/lightning/pytorch/loops/fetchers.py:99

        if self._combined_loader is not None:
            self._combined_loader.reset()
        self.iterator = None


class _PrefetchDataFetcher(_DataFetcher):
    """This class is used to control batch fetching flow.

    Args:
        prefetch_batches: Number of batches to pre-fetch. Pre-fetching at least 1 batch is necessary to properly track
            whether a batch is the last one (available with :attr:`self.done`) when the length is not available. The
            value of this argument is ignored when the length is available.

    """

    def __init__(self, prefetch_batches: int = 1) -> None:
        super().__init__()
        if prefetch_batches < 0:
            raise ValueError("`prefetch_batches` should at least be 0.")
        self.prefetch_batches = prefetch_batches
        self.batches: list[Any] = []

    @override
    def __iter__(self) -> "_PrefetchDataFetcher":
        super().__iter__()
        if self.length is not None:
            # ignore pre-fetching, it's not necessary
            return self
        # prefetch batches to know when the iterator will be exhausted in advance
        for _ in range(self.prefetch_batches):
            try:
                batch = super().__next__()
                self.batches.append(batch)
            except StopIteration:
                # this would only happen when prefetch_batches > the number of batches available and makes
                # `__next__` jump directly to the empty iterator case without trying to fetch again
                break

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Pass 0 to disable prefetching (that's the minimum, no negative needed)
2. Clamp config values: max(0, prefetch_batches)
3. Validate the CLI/config type with a non-negative constraint

Example fix

# before
fetcher = _PrefetchDataFetcher(prefetch_batches=cfg.prefetch - 2)  # may be negative
# after
fetcher = _PrefetchDataFetcher(prefetch_batches=max(0, cfg.prefetch - 2))

prefetch_batches = max(0, int(prefetch_batches))

When it happens

Trigger: Constructing _PrefetchDataFetcher(prefetch_batches=-1), or a config/CLI value that flows in unvalidated (e.g. a negative int from a YAML config or an off-by-one computation).

Common situations: Experiments tuning prefetch depth where a computed value goes negative (e.g. prefetch = num_workers - something), or CLI arg parsing accepting negatives.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• {seed} is not in bounds, numpy accepts from {min_seed_value}
• Expected samples ({samples}) to be greater or equal than bat
• Unknown configuration for model optimizers. Output from `mod
• The lr scheduler dict must have the key "scheduler" with its
• The "interval" key in lr scheduler dict must be "step" or "e

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