unslothai/unsloth · error · ValueError

compile_transformer must be one of off / on / auto

Error message

compile_transformer must be one of off / on / auto

What it means

The validator rejected a compile_transformer value outside ('off', 'on', 'auto'). This flag controls torch.compile of the transformer backbone ('auto' lets the trainer decide per family/hardware). The value is normalized with strip().lower() before the check, so casing and whitespace are forgiven — the error means the string content itself is unrecognized.

Source

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

            if save_steps:
                raise ValueError(
                    f"save_steps is not supported for {resolved_family}: its trainer writes no "
                    f"checkpoint bundle. Leave it at 0; the adapter is still saved at the end."
                )
        try:
            ema_decay = float(self.ema_decay or 0.0)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"ema_decay must be a number, got {self.ema_decay!r}") from exc
        # decay = 1.0 would freeze the shadow at its init forever; the update is shadow * decay + param * (1 - decay), so valid decays live in [0, 1).
        if not 0.0 <= ema_decay < 1.0:
            raise ValueError("ema_decay must be in [0, 1); 0 disables the EMA adapter")
        # A blank cond_cache_dir (the Studio default when unset) means "off", not cwd.
        cond_cache_dir = (
            str(self.cond_cache_dir).strip() if self.cond_cache_dir is not None else ""
        ) or None
        compile_transformer = str(self.compile_transformer or "auto").strip().lower()
        if compile_transformer not in ("off", "on", "auto"):
            raise ValueError("compile_transformer must be one of off / on / auto")
        base_precision = str(self.base_precision or "nf4").strip().lower()
        if base_precision not in ("nf4", "bf16", "int8", "fp8", "mxfp8", "auto"):
            raise ValueError("base_precision must be one of nf4 / bf16 / int8 / fp8 / mxfp8 / auto")
        # base_precision is a DiT-only lever, so the dense-mode gates apply only to the DiT families. The mode-name check above still runs for every family.
        if resolved_family != "sdxl" and base_precision in ("bf16", "int8", "fp8", "mxfp8"):
            if repo_is_prequantized(self.base_model):
                raise ValueError(
                    f"base_precision={base_precision!r} needs a dense base repo, but "
                    f"'{self.base_model}' is already bitsandbytes-quantized. Pick the "
                    f"family's dense (bf16) base repo for this mode, or use nf4/auto."
                )
            if self.mixed_precision != "bf16":
                raise ValueError(
                    f"base_precision={base_precision!r} trains in bf16 compute; set "
                    f"mixed_precision to bf16."
                )
            # Refuse a scheme this family's DiT is known to corrupt, and also one the training bar holds back while
            # inference allows it: qwen-image fp8 now renders inside the accuracy gate, but no one has measured whether a

View on GitHub (pinned to 203007d190)

Solutions

1. Use exactly 'off', 'on', or 'auto' (case-insensitive; whitespace tolerated).
2. Map booleans before submitting: True -> 'on', False -> 'off'.
3. Prefer 'auto' unless you specifically need to force or disable compilation.

Example fix

# before
config = TrainConfig(compile_transformer='true')

# after
config = TrainConfig(compile_transformer='on')

VALID_COMPILE = {"off", "on", "auto"}

def check_compile_transformer(v) -> str:
    s = str(v or "auto").strip().lower()
    if s in ("true", "yes", "1"):
        s = "on"
    elif s in ("false", "no", "0"):
        s = "off"
    if s not in VALID_COMPILE:
        raise ValueError(f"compile_transformer must be off / on / auto, got {v!r}")
    return s

def is_valid_compile_transformer(v) -> bool:
    return str(v or "auto").strip().lower() in {"off", "on", "auto"}

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

When it happens

Trigger: Passing compile_transformer='true'/'false' (boolean-style strings), 'yes', 'never', 'force', or a bool True which str()s to 'true'. The field is a tri-state, not a boolean — there is no 'true' spelling.

Common situations: Frontends sending checkbox booleans as 'true'/'false'; users writing yes/no from other config dialects; assuming 'auto' has spellings like 'automatic'.

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/d3660d63e6596684. Report an issue: GitHub.