unslothai/unsloth · error · ValueError

cache_variants must be between 1 and 16

Error message

cache_variants must be between 1 and 16

What it means

The validator rejected cache_variants outside [1, 16]. cache_variants controls how many latent/caption variant caches are prepared per sample (e.g. multi-crop or multi-caption caching); 0 means no training data is cached and >16 blows up cache disk/time for no benefit. The bound is enforced in validation before any GPU/cache work begins.

Source

Thrown at studio/backend/core/training/diffusion_train_common.py:1051

            )
        if self.mixed_precision not in ("bf16", "fp16", "no"):
            raise ValueError("mixed_precision must be one of bf16 / fp16 / no")
        # torch.manual_seed unpacks int64/uint64, so anything wider raises inside the trainer, after eviction. Catch it here.
        if not -(2**63) <= int(self.seed) <= 2**64 - 1:
            raise ValueError("seed must fit in torch's 64-bit range")
        # Refuse fp16 for a bf16-only DiT family up front, before evicting resident models.
        if self.mixed_precision == "fp16" and resolved_family in _FORCE_BF16_FAMILIES:
            raise ValueError(
                f"'{resolved_family}' LoRA training requires bf16: fp16 overflows its fp32 "
                f"RoPE / embedder internals. Set mixed precision to bf16."
            )
        if str(self.lr_scheduler) not in _LR_SCHEDULERS:
            raise ValueError(
                f"lr_scheduler must be one of {', '.join(sorted(_LR_SCHEDULERS))}; "
                f"got {self.lr_scheduler!r}"
            )
        if not 1 <= int(self.cache_variants) <= 16:
            raise ValueError("cache_variants must be between 1 and 16")
        # Checkpointing knobs. Rejected here, before the route evicts resident GPU models, rather than deep in the loop.
        try:
            save_steps = int(self.save_steps or 0)
            save_total_limit = int(self.save_total_limit or 0)
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"save_steps / save_total_limit must be whole numbers, got "
                f"{self.save_steps!r} / {self.save_total_limit!r}"
            ) from exc
        if save_steps < 0:
            raise ValueError("save_steps must be >= 0 (0 disables periodic checkpoints)")
        if save_total_limit < 0:
            raise ValueError("save_total_limit must be >= 0 (0 keeps every checkpoint)")
        # A blank resume path (the Studio default when the field is present but unset) means "fresh run", not the outputs root.
        resume_from_checkpoint = (
            str(self.resume_from_checkpoint).strip()
            if self.resume_from_checkpoint is not None
            else ""

View on GitHub (pinned to 203007d190)

Solutions

1. Set cache_variants between 1 and 16 (1 is the conservative default for single-variant caching).
2. If disk space is tight, lower it toward 1 rather than 0 — 0 is invalid, not 'off'.
3. Bound sweep grids for this field to 1..16.

Example fix

# before
config = TrainConfig(cache_variants=0)

# after
config = TrainConfig(cache_variants=1)

def check_cache_variants(v) -> int:
    n = int(v) if v not in (None, "") else 1
    if not 1 <= n <= 16:
        raise ValueError(f"cache_variants must be between 1 and 16, got {v!r}")
    return n

def is_valid_cache_variants(v) -> bool:
    try:
        return 1 <= int(v) <= 16
    except (TypeError, ValueError):
        return False

try:
    session.submit_training(config)
except ValueError as e:
    if "cache_variants" in str(e):
        config.cache_variants = 1
        session.submit_training(config)
    else:
        raise

When it happens

Trigger: A training request with cache_variants=0, 17+, or a string parsing to such a value. Commonly from config defaults left at 0, or experiment sweeps probing large cache multipliers.

Common situations: New configs copied from a template where the field was left 0; misunderstanding the field as a boolean; aggressive data-augmentation attempts pushing variants very high.

Related errors

• gradient_accumulation_steps must be >= 1
• lora_rank must be >= 1
• lora_alpha must be >= 1 (a zero/negative alpha scales the ad
• resolution must be a multiple of 8 and >= 64
• mixed_precision must be one of bf16 / fp16 / no

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/7f17360f181d4ff4. Report an issue: GitHub.