Lightning-AI/pytorch-lightning · error · ValueError

Expected samples ({samples}) to be greater or equal than bat

Error message

Expected samples ({samples}) to be greater or equal than batches ({batches})

What it means

`ThroughputCollector.update(...)`/Throughput metric's `update` accumulates per-step time, batch count and sample count; a basic invariant is that each batch contains at least one sample, so `samples >= batches` must hold. Passing fewer samples than batches (e.g. samples=0 with batches>0, or mixing up argument order) raises this ValueError.

Source

Thrown at src/lightning/fabric/utilities/throughput.py:156

        flops: Optional[int] = None,
    ) -> None:
        """Update throughput metrics.

        Args:
            time: Total elapsed time in seconds. It should monotonically increase by the iteration time with each
                call.
            batches: Total batches seen per device. It should monotonically increase with each call.
            samples: Total samples seen per device. It should monotonically increase by the batch size with each call.
            lengths: Total length of the samples seen. It should monotonically increase by the lengths of a batch with
                each call.
            flops: Flops elapased per device since last ``update()`` call. You can easily compute this by using
                :func:`measure_flops` and multiplying it by the number of batches that have been processed.
                The value might be different in each device if the batch size is not the same.

        """
        self._time.append(time)
        if samples < batches:
            raise ValueError(f"Expected samples ({samples}) to be greater or equal than batches ({batches})")
        self._batches.append(batches)
        self._samples.append(samples)
        if lengths is not None:
            if lengths < samples:
                raise ValueError(f"Expected lengths ({lengths}) to be greater or equal than samples ({samples})")
            self._lengths.append(lengths)
            if len(self._samples) != len(self._lengths):
                raise RuntimeError(
                    f"If lengths are passed ({len(self._lengths)}), there needs to be the same number of samples"
                    f" ({len(self._samples)})"
                )
        if flops is not None:
            # sum of flops across ranks
            self._flops.append(flops * self.world_size)

    def compute(self) -> _THROUGHPUT_METRICS:
        """Compute throughput metrics."""
        metrics = {

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Check argument order and pass samples = total items across the update window (>= number of batches)
2. Use keyword arguments: `update(time=..., batches=..., samples=...)`
3. Compute samples as sum of per-batch sizes, not a single batch size; guard with `if samples < batches: raise/skip`

Example fix

# before
collector.update(time=dt, batches=steps, samples=batch_size)  # batch_size < steps -> error

# after
collector.update(time=dt, batches=steps, samples=batch_size * steps)

assert samples >= batches, f"samples ({samples}) < batches ({batches})"

When it happens

Trigger: Calling `update(time=t, batches=n, samples=m)` with m < n, commonly by swapping the `batches` and `samples` arguments, passing `samples=0`, or computing samples as batch_size instead of batch_size*num_batches.

Common situations: Argument-order mixups (samples and batches are adjacent ints), unit tests feeding zeros, dynamic batch sizes where the last partial batch's sample count is computed incorrectly, position vs keyword argument mismatch after an API update.

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 lengths ({lengths}) to be greater or equal than sam
• 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/c79decfa91695d4f. Report an issue: GitHub.