unslothai/unsloth · error · ValueError

base_precision={base_precision!r} is not validated for train

Error message

base_precision={base_precision!r} is not validated for training {resolved_family}. Use 'nf4', 'int8', 'bf16', or 'auto'.

What it means

Beyond the hard-coded refusals, the trainer consults _family_train_denied(family, precision) from core.inference.diffusion_transformer_quant — the strict superset of inference denials plus training-only holds. If a scheme is cleared for rendering but never measured for LoRA convergence (e.g. qwen-image fp8), it is rejected here rather than trained on faith.

Source

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

            # inference allows it: qwen-image fp8 now renders inside the accuracy gate, but no one has measured whether a
            # LoRA converges against fp8-frozen linears, so it fails fast here rather than silently training on faith.
            # MiniMax-H3 runs all three modalities through one set of linears, so the
            # per-family activation range the fp8 module filter was measured against does not
            # describe it. Refuse the float8 modes rather than train against a clipped forward.
            if resolved_family == "minimax-h3" and base_precision in ("fp8", "mxfp8"):
                raise ValueError(
                    f"base_precision={base_precision!r} is not supported for minimax-h3: its "
                    f"packed sequence mixes video, audio and text through one set of linears, "
                    f"so the activation range fp8 was measured against does not apply. Use "
                    f"'nf4', 'int8', 'bf16', or 'auto'."
                )
            # _family_train_denied, not _family_denied: it is the strict superset (every inference
            # deny plus the training-only ones), so importing the narrower helper here would let a
            # scheme cleared only for rendering reach a trainer.
            from core.inference.diffusion_transformer_quant import _family_train_denied

            if _family_train_denied(resolved_family, base_precision):
                raise ValueError(
                    f"base_precision={base_precision!r} is not validated for training "
                    f"{resolved_family}. Use 'nf4', 'int8', 'bf16', or 'auto'."
                )
        # flow_shift: None resolves to the family default ("auto" only for qwen-image, whose scheduler skips its static shift under use_dynamic_shifting); an explicit value is validated and kept.
        flow_shift = self.flow_shift
        if flow_shift is None:
            flow_shift = "auto" if resolved_family in AUTO_FLOW_SHIFT_FAMILIES else 1.0
        if isinstance(flow_shift, str):
            flow_shift = flow_shift.strip().lower()
            if flow_shift != "auto":
                try:
                    flow_shift = float(flow_shift)
                except ValueError as exc:
                    raise ValueError(
                        f"flow_shift must be a positive number or 'auto', got {self.flow_shift!r}"
                    ) from exc
        if not isinstance(flow_shift, str):
            flow_shift = float(flow_shift)

View on GitHub (pinned to 203007d190)

Solutions

1. Switch base_precision to one of the validated training schemes: 'nf4', 'int8', 'bf16', or 'auto'.
2. Check core/inference/diffusion_transformer_quant.py's deny tables to see which schemes are training-validated for the family.
3. If you control the bar, measure LoRA convergence for the scheme on the family and update _family_train_denied deliberately — do not bypass it.

Example fix

# before
cfg = DiffusionLoraConfig(base_model='Qwen/Qwen-Image', base_precision='fp8', mixed_precision='bf16')
# after
cfg = DiffusionLoraConfig(base_model='Qwen/Qwen-Image', base_precision='bf16', mixed_precision='bf16')

from core.inference.diffusion_transformer_quant import _family_train_denied
def validated_precision(family, base_precision):
    bp = str(base_precision or 'nf4').strip().lower()
    if _family_train_denied(family, bp):
        raise ValueError(f'{bp} not validated for training {family}')
    return bp

When it happens

Trigger: A non-SDXL family with a dense base_precision that passes the bf16-compute and MiniMax gates but is listed in the training-deny table: currently qwen-image with 'fp8' (and any family/scheme pair _family_train_denied returns True for).

Common situations: Inference works fine with a quantized checkpoint, so the same quantization is assumed trainable; a new scheme is enabled for inference in a newer release but its training validation lags.

Related errors

• base_precision={base_precision!r} trains in bf16 compute; se
• gradient_accumulation_steps must be >= 1
• resolution must be a multiple of 8 and >= 64
• '{resolved_family}' trains at a resolution that is a multipl
• base_precision={base_precision!r} is not supported for minim

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