{"record":{"id":"d3660d63e6596684","repo":"unslothai/unsloth","slug":"compile-transformer-must-be-one-of-off-on-auto","errorCode":null,"errorMessage":"compile_transformer must be one of off / on / auto","messagePattern":"compile_transformer must be one of off / on / auto","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/training/diffusion_train_common.py","lineNumber":1101,"sourceCode":"            if save_steps:\n                raise ValueError(\n                    f\"save_steps is not supported for {resolved_family}: its trainer writes no \"\n                    f\"checkpoint bundle. Leave it at 0; the adapter is still saved at the end.\"\n                )\n        try:\n            ema_decay = float(self.ema_decay or 0.0)\n        except (TypeError, ValueError) as exc:\n            raise ValueError(f\"ema_decay must be a number, got {self.ema_decay!r}\") from exc\n        # 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).\n        if not 0.0 <= ema_decay < 1.0:\n            raise ValueError(\"ema_decay must be in [0, 1); 0 disables the EMA adapter\")\n        # A blank cond_cache_dir (the Studio default when unset) means \"off\", not cwd.\n        cond_cache_dir = (\n            str(self.cond_cache_dir).strip() if self.cond_cache_dir is not None else \"\"\n        ) or None\n        compile_transformer = str(self.compile_transformer or \"auto\").strip().lower()\n        if compile_transformer not in (\"off\", \"on\", \"auto\"):\n            raise ValueError(\"compile_transformer must be one of off / on / auto\")\n        base_precision = str(self.base_precision or \"nf4\").strip().lower()\n        if base_precision not in (\"nf4\", \"bf16\", \"int8\", \"fp8\", \"mxfp8\", \"auto\"):\n            raise ValueError(\"base_precision must be one of nf4 / bf16 / int8 / fp8 / mxfp8 / auto\")\n        # 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.\n        if resolved_family != \"sdxl\" and base_precision in (\"bf16\", \"int8\", \"fp8\", \"mxfp8\"):\n            if repo_is_prequantized(self.base_model):\n                raise ValueError(\n                    f\"base_precision={base_precision!r} needs a dense base repo, but \"\n                    f\"'{self.base_model}' is already bitsandbytes-quantized. Pick the \"\n                    f\"family's dense (bf16) base repo for this mode, or use nf4/auto.\"\n                )\n            if self.mixed_precision != \"bf16\":\n                raise ValueError(\n                    f\"base_precision={base_precision!r} trains in bf16 compute; set \"\n                    f\"mixed_precision to bf16.\"\n                )\n            # Refuse a scheme this family's DiT is known to corrupt, and also one the training bar holds back while\n            # inference allows it: qwen-image fp8 now renders inside the accuracy gate, but no one has measured whether a","sourceCodeStart":1083,"sourceCodeEnd":1119,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/training/diffusion_train_common.py#L1083-L1119","documentation":"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.","triggerScenarios":"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.","commonSituations":"Frontends sending checkbox booleans as 'true'/'false'; users writing yes/no from other config dialects; assuming 'auto' has spellings like 'automatic'.","solutions":["Use exactly 'off', 'on', or 'auto' (case-insensitive; whitespace tolerated).","Map booleans before submitting: True -> 'on', False -> 'off'.","Prefer 'auto' unless you specifically need to force or disable compilation."],"exampleFix":"# before\nconfig = TrainConfig(compile_transformer='true')\n\n# after\nconfig = TrainConfig(compile_transformer='on')","handlingStrategy":"validation","validationCode":"VALID_COMPILE = {\"off\", \"on\", \"auto\"}\n\ndef check_compile_transformer(v) -> str:\n    s = str(v or \"auto\").strip().lower()\n    if s in (\"true\", \"yes\", \"1\"):\n        s = \"on\"\n    elif s in (\"false\", \"no\", \"0\"):\n        s = \"off\"\n    if s not in VALID_COMPILE:\n        raise ValueError(f\"compile_transformer must be off / on / auto, got {v!r}\")\n    return s","typeGuard":"def is_valid_compile_transformer(v) -> bool:\n    return str(v or \"auto\").strip().lower() in {\"off\", \"on\", \"auto\"}","tryCatchPattern":"try:\n    session.submit_training(config)\nexcept ValueError as e:\n    if \"compile_transformer\" in str(e):\n        config.compile_transformer = \"auto\"\n        session.submit_training(config)\n    else:\n        raise","preventionTips":["Send 'off'/'on'/'auto' strings, not booleans — there is no 'true' spelling.","Map bool -> 'on'/'off' at your API boundary.","Default to 'auto' unless you have measured a reason to force compilation."],"tags":["training","torch-compile","configuration","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}