unslothai/unsloth · error · ValueError

lora_rank must be >= 1

Error message

lora_rank must be >= 1

What it means

The training-config validator rejected lora_rank < 1. LoRA rank determines the dimensionality of the low-rank adapter matrices; rank 0 or negative has no mathematical meaning and would produce empty/negative-shaped tensors deep in the trainer. It is checked up front so the request fails before GPU models are evicted.

Source

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

    resolved_family: str = "sdxl"

    def normalized(self) -> "DiffusionLoraConfig":
        """Return a copy with derived/validated fields filled in. Raises ValueError on a
        request that cannot train (bad numbers, or an untrainable base model).

        Also coerces values that arrive as strings/blanks through the Studio config path
        (``learning_rate`` is preserved as a string there; ``hf_token`` defaults to "")."""
        resolved_family = resolve_trainable_family(self.base_model, self.model_family)
        if self.train_steps < 1:
            raise ValueError("train_steps must be >= 1")
        if not 0 <= int(self.num_epochs) <= 1000:
            raise ValueError("num_epochs must be between 0 and 1000 (0 uses train_steps)")
        if self.train_batch_size < 1:
            raise ValueError("train_batch_size must be >= 1")
        if self.gradient_accumulation_steps < 1:
            raise ValueError("gradient_accumulation_steps must be >= 1")
        if self.lora_rank < 1:
            raise ValueError("lora_rank must be >= 1")
        if self.lora_alpha is not None and self.lora_alpha < 1:
            raise ValueError(
                "lora_alpha must be >= 1 (a zero/negative alpha scales the adapter to nothing)"
            )
        if self.resolution < 64 or self.resolution % 8 != 0:
            raise ValueError("resolution must be a multiple of 8 and >= 64")
        # A video family's VAE compresses space by 32, so an off-grid resolution changes the
        # latent geometry silently. Refuse it here, before the GPU models are evicted.
        if (
            resolved_family in TRAINABLE_VIDEO_FAMILIES
            and self.resolution % _VIDEO_RESOLUTION_MULTIPLE != 0
        ):
            raise ValueError(
                f"'{resolved_family}' trains at a resolution that is a multiple of "
                f"{_VIDEO_RESOLUTION_MULTIPLE} (its VAE compresses space by that factor); "
                f"got {self.resolution}."
            )
        if self.mixed_precision not in ("bf16", "fp16", "no"):

View on GitHub (pinned to 203007d190)

Solutions

1. Set lora_rank to a positive integer (typical values: 8, 16, 32, 64).
2. If you meant 'train without LoRA', that is not expressed via rank — use the appropriate full-finetune flag instead of rank 0.
3. Sanitize sweep grids to exclude non-positive ranks before submitting jobs.

Example fix

# before
config = TrainConfig(lora_rank=0)

# after
config = TrainConfig(lora_rank=16)

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

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

try:
    session.submit_training(config)
except ValueError as e:
    if "lora_rank" in str(e):
        config.lora_rank = 16  # safe default
        session.submit_training(config)
    else:
        raise

When it happens

Trigger: A training request with lora_rank = 0, a negative integer, or a coerced string ('0', '', '-4'). Commonly triggered from auto-tuning scripts that sweep ranks and include an invalid bound, or forms defaulting to 0.

Common situations: Hyperparameter sweeps that include rank 0 as a 'no LoRA' baseline; hand-edited config files; UI numeric inputs that default to 0; porting configs from tutorials that use rank as a boolean-like switch.

Related errors

• gradient_accumulation_steps 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
• seed must fit in torch's 64-bit range

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