{"record":{"id":"7f17360f181d4ff4","repo":"unslothai/unsloth","slug":"cache-variants-must-be-between-1-and-16","errorCode":null,"errorMessage":"cache_variants must be between 1 and 16","messagePattern":"cache_variants must be between 1 and 16","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/training/diffusion_train_common.py","lineNumber":1051,"sourceCode":"            )\n        if self.mixed_precision not in (\"bf16\", \"fp16\", \"no\"):\n            raise ValueError(\"mixed_precision must be one of bf16 / fp16 / no\")\n        # torch.manual_seed unpacks int64/uint64, so anything wider raises inside the trainer, after eviction. Catch it here.\n        if not -(2**63) <= int(self.seed) <= 2**64 - 1:\n            raise ValueError(\"seed must fit in torch's 64-bit range\")\n        # Refuse fp16 for a bf16-only DiT family up front, before evicting resident models.\n        if self.mixed_precision == \"fp16\" and resolved_family in _FORCE_BF16_FAMILIES:\n            raise ValueError(\n                f\"'{resolved_family}' LoRA training requires bf16: fp16 overflows its fp32 \"\n                f\"RoPE / embedder internals. Set mixed precision to bf16.\"\n            )\n        if str(self.lr_scheduler) not in _LR_SCHEDULERS:\n            raise ValueError(\n                f\"lr_scheduler must be one of {', '.join(sorted(_LR_SCHEDULERS))}; \"\n                f\"got {self.lr_scheduler!r}\"\n            )\n        if not 1 <= int(self.cache_variants) <= 16:\n            raise ValueError(\"cache_variants must be between 1 and 16\")\n        # Checkpointing knobs. Rejected here, before the route evicts resident GPU models, rather than deep in the loop.\n        try:\n            save_steps = int(self.save_steps or 0)\n            save_total_limit = int(self.save_total_limit or 0)\n        except (TypeError, ValueError) as exc:\n            raise ValueError(\n                f\"save_steps / save_total_limit must be whole numbers, got \"\n                f\"{self.save_steps!r} / {self.save_total_limit!r}\"\n            ) from exc\n        if save_steps < 0:\n            raise ValueError(\"save_steps must be >= 0 (0 disables periodic checkpoints)\")\n        if save_total_limit < 0:\n            raise ValueError(\"save_total_limit must be >= 0 (0 keeps every checkpoint)\")\n        # A blank resume path (the Studio default when the field is present but unset) means \"fresh run\", not the outputs root.\n        resume_from_checkpoint = (\n            str(self.resume_from_checkpoint).strip()\n            if self.resume_from_checkpoint is not None\n            else \"\"","sourceCodeStart":1033,"sourceCodeEnd":1069,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/training/diffusion_train_common.py#L1033-L1069","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set cache_variants between 1 and 16 (1 is the conservative default for single-variant caching).","If disk space is tight, lower it toward 1 rather than 0 — 0 is invalid, not 'off'.","Bound sweep grids for this field to 1..16."],"exampleFix":"# before\nconfig = TrainConfig(cache_variants=0)\n\n# after\nconfig = TrainConfig(cache_variants=1)","handlingStrategy":"validation","validationCode":"def check_cache_variants(v) -> int:\n    n = int(v) if v not in (None, \"\") else 1\n    if not 1 <= n <= 16:\n        raise ValueError(f\"cache_variants must be between 1 and 16, got {v!r}\")\n    return n","typeGuard":"def is_valid_cache_variants(v) -> bool:\n    try:\n        return 1 <= int(v) <= 16\n    except (TypeError, ValueError):\n        return False","tryCatchPattern":"try:\n    session.submit_training(config)\nexcept ValueError as e:\n    if \"cache_variants\" in str(e):\n        config.cache_variants = 1\n        session.submit_training(config)\n    else:\n        raise","preventionTips":["Default cache_variants to 1 in templates; it is not a boolean and has no 'off' value.","Bound sweep grids to 1..16.","When disk-constrained, lower the value instead of zeroing it."],"tags":["training","caching","configuration","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}