huggingface/pytorch-image-models · error · ValueError
num_batches must be a positive integer when specified.
Error message
num_batches must be a positive integer when specified.
What it means
num_batches (optional cap/override on the number of batches per epoch) must, when provided, be a positive integer; None/non-positive/fractional values fail this check in the constructor.
Source
Thrown at timm/data/scheduled_sampler.py:69
seed: int = 0,
drop_last: bool = True,
shuffle_schedule: bool = True,
num_batches: Optional[int] = None,
choice_schedule: str = 'constant',
schedule_epochs: Optional[int] = None,
schedule_spread: float = 0.65,
schedule_random_mix: float = 0.1,
) -> None:
if not hasattr(sampler, '__len__'):
raise TypeError('ScheduledBatchSampler requires a sampler with a length.')
if len(sampler) <= 0:
raise ValueError('ScheduledBatchSampler requires a non-empty sampler.')
if not batch_sizes:
raise ValueError('batch_sizes must contain at least one value.')
if any(int(batch_size) != batch_size or batch_size <= 0 for batch_size in batch_sizes):
raise ValueError('All scheduled batch sizes must be positive integers.')
if num_batches is not None and (int(num_batches) != num_batches or num_batches <= 0):
raise ValueError('num_batches must be a positive integer when specified.')
if choice_schedule not in ('constant', 'progressive'):
raise ValueError("choice_schedule must be 'constant' or 'progressive'.")
if choice_schedule == 'progressive':
if len(batch_sizes) < 2:
raise ValueError('A progressive schedule requires at least two choices.')
if schedule_epochs is None or int(schedule_epochs) != schedule_epochs or schedule_epochs <= 0:
raise ValueError('schedule_epochs must be a positive integer for a progressive schedule.')
if schedule_spread < 0:
raise ValueError('schedule_spread must be non-negative.')
if not 0 <= schedule_random_mix <= 1:
raise ValueError('schedule_random_mix must be between 0 and 1.')
self.sampler = sampler
self.batch_sizes = tuple(int(batch_size) for batch_size in batch_sizes)
self.choice_weights = self._normalize_choice_weights(choice_weights)
self._active_choices = tuple(
choice_index
for choice_index, choice_weight in enumerate(self.choice_weights)View on GitHub (pinned to 9a5261e31b)
Solutions
- Omit num_batches (pass None) to let the sampler infer it from the dataset length.
- Compute it defensively: num_batches = max(1, round(steps)) or verify steps > 0 before passing.
- Fix the underlying steps-per-epoch calculation (check batch size vs dataset size).
Example fix
# before steps = len(dataset) // batch_size # 0 when dataset < batch_size sched = ScheduledBatchSampler(s, batch_sizes=[b], num_batches=steps) # after steps = max(1, len(dataset) // batch_size) # or omit num_batches entirely sched = ScheduledBatchSampler(s, batch_sizes=[b], num_batches=steps)
Defensive patterns
Strategy: validation
Validate before calling
num_batches = None if steps is None else max(1, int(round(steps))) if steps and steps > 0 else None
Prevention
- Prefer omitting num_batches (let the sampler infer).
- Clamp computed step counts to >= 1.
- Check steps-per-epoch math against dataset size.
When it happens
Trigger: ScheduledBatchSampler(..., num_batches=0), num_batches=-5, num_batches=2.5, or num_batches computed as len(dataset)//0 (ZeroDivision caught earlier) / a float division result.
Common situations: Computing num_batches from steps-per-epoch math that yields 0 on a tiny dataset; config typos; passing math.floor results of negative numbers.
Related errors
- All scheduled batch sizes must be positive integers.
- A progressive schedule requires at least two choices.
- schedule_epochs must be a positive integer for a progressive
- schedule_spread must be non-negative.
- schedule_random_mix must be between 0 and 1.
AI-assisted analysis of huggingface/pytorch-image-models@9a5261e31b (2026-08-27).
Data as JSON: /api/errors/fb65660962a96ee9.
Report an issue: GitHub.