unslothai/unsloth · error · ValueError

flow_shift must be a finite number > 0 (1.0 disables the shi

Error message

flow_shift must be a finite number > 0 (1.0 disables the shift), or 'auto'

What it means

After successful float conversion, flow_shift must be finite and strictly positive. JSON parsers happily accept 1e309, which Python floats to inf — an infinite shift would poison every sampled sigma while training progress looks normal — so math.isfinite is enforced explicitly. 1.0 disables the shift.

Source

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

                )
        # 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)
            # isfinite as well as positive: JSON accepts 1e309, which floats to inf and would poison every sampled sigma while progress looks normal.
            if not math.isfinite(flow_shift) or flow_shift <= 0:
                raise ValueError(
                    "flow_shift must be a finite number > 0 (1.0 disables the shift), or 'auto'"
                )
        try:
            cfg_dropout = float(self.cfg_dropout or 0.0)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"cfg_dropout must be a number, got {self.cfg_dropout!r}") from exc
        if not 0.0 <= cfg_dropout <= 1.0:
            raise ValueError("cfg_dropout must be between 0 and 1")
        weighting_scheme = str(self.weighting_scheme or "none").strip().lower()
        if weighting_scheme not in ("none", "bell"):
            raise ValueError("weighting_scheme must be one of none / bell")
        # A zero/negative gamma would zero out (or invert) the min-SNR weight and silently train on a degenerate loss; None is the documented disable.
        if self.snr_gamma is not None and float(self.snr_gamma) <= 0:
            raise ValueError("snr_gamma must be > 0, or null to disable min-SNR weighting")
        # learning_rate can arrive as a string ("1e-4") from the Studio config path, so coerce it before AdamW sees it.
        try:
            learning_rate = float(self.learning_rate)
        except (TypeError, ValueError) as exc:

View on GitHub (pinned to 203007d190)

Solutions

1. Use flow_shift=1.0 to disable shifting — not 0.
2. Ensure computed values are bounded: clamp or validate with math.isfinite before assigning.
3. For qwen-image dynamic shifting, prefer flow_shift='auto' rather than a hand-picked extreme value.

Example fix

# before
cfg.flow_shift = 0  # intended 'no shift'
# after
cfg.flow_shift = 1.0  # 1.0 disables the shift

import math
def safe_flow_shift(v):
    if isinstance(v, str):
        v = None if v.strip().lower() == 'auto' else float(v)
    if v is not None and (not math.isfinite(v) or v <= 0):
        raise ValueError('flow_shift must be finite and > 0; use 1.0 to disable')
    return v

When it happens

Trigger: flow_shift = float('inf'), float('nan'), 0, a negative number, or a JSON value like 1e309 / -0.0 that floats to a non-finite or non-positive value.

Common situations: Programmatic config generation that divides by zero or overflows; hand-written JSON with huge exponents; treating 0 as 'no shift' when 1.0 is the actual disable value.

Related errors

• flow_shift must be a positive number or 'auto', got {self.fl
• 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

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