Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Stop unsloth train from ignoring config keys it does not know (#10452)
Nilay7b691664d9de
diff --git a/unsloth_cli/commands/train.py b/unsloth_cli/commands/train.pyindex 8b6aac4f21f..2175cf0eccd 100644--- a/unsloth_cli/commands/train.py+++ b/unsloth_cli/commands/train.py@@ -9,7 +9,7 @@ import typerfrom unsloth_cli._inference import ensure_studio_backend_pathfrom unsloth_cli._studio_deps import studio_backend_imports-from unsloth_cli.config import Config, load_config+from unsloth_cli.config import Config, ConfigError, load_configfrom unsloth_cli.options import add_options_from_config@@ -71,7 +71,7 @@ def train("""Launch training using the existing Unsloth training backend."""try:cfg = load_config(config)- except FileNotFoundError as e:+ except (FileNotFoundError, ConfigError) as e:typer.echo(f"Error: {e}", err = True)raise typer.Exit(code = 2)diff --git a/unsloth_cli/config.py b/unsloth_cli/config.pyindex dbc7701f706..66c3748de99 100644--- a/unsloth_cli/config.py+++ b/unsloth_cli/config.py@@ -5,16 +5,20 @@ from pathlib import Pathfrom typing import Literal, Optional, Listimport yaml-from pydantic import BaseModel, Field+from pydantic import BaseModel, ConfigDict, Field, ValidationErrorclass DataConfig(BaseModel):+ model_config = ConfigDict(extra = "forbid")+dataset: Optional[str] = Nonelocal_dataset: Optional[List[str]] = Noneformat_type: Literal["auto", "alpaca", "chatml", "sharegpt"] = "auto"class TrainingConfig(BaseModel):+ model_config = ConfigDict(extra = "forbid")+training_type: Literal["lora", "full"] = "lora"max_seq_length: int = 2048load_in_4bit: bool = True@@ -34,6 +38,8 @@ class TrainingConfig(BaseModel):class LoraConfig(BaseModel):+ model_config = ConfigDict(extra = "forbid")+lora_r: int = 64lora_alpha: int = 16lora_dropout: float = 0.0@@ -49,6 +55,8 @@ class LoraConfig(BaseModel):class LoggingConfig(BaseModel):+ model_config = ConfigDict(extra = "forbid")+enable_wandb: bool = Falsewandb_project: str = "unsloth-training"wandb_token: Optional[str] = None@@ -58,6 +66,8 @@ class LoggingConfig(BaseModel):class Config(BaseModel):+ model_config = ConfigDict(extra = "forbid")+model: Optional[str] = Nonedata: DataConfig = Field(default_factory = DataConfig)training: TrainingConfig = Field(default_factory = TrainingConfig)@@ -128,6 +138,56 @@ class Config(BaseModel):}+class ConfigError(ValueError):+ pass+++def _section_for_field(name: str) -> Optional[str]:+ for section, field_info in Config.model_fields.items():+ annotation = field_info.annotation+ if isinstance(annotation, type) and issubclass(annotation, BaseModel):+ if name in annotation.model_fields:+ return section+ return None+++def _describe_unknown_key(loc: tuple) -> str:+ key = str(loc[-1])+ parent = str(loc[-2]) if len(loc) > 1 else None+ where = f"in section '{parent}'" if parent else "at the top level"+ canonical = key.replace("-", "_")+ section = _section_for_field(canonical)+ subject = "it" if canonical == key else f"'{canonical}'"++ if section is not None and section == parent:+ return f"unknown key '{key}' {where}: did you mean '{canonical}'?"+ if section is not None:+ return f"unknown key '{key}' {where}: {subject} belongs under '{section}:'"+ if canonical in Config.model_fields:+ if parent is None:+ return f"unknown key '{key}' {where}: did you mean '{canonical}'?"+ return f"unknown key '{key}' {where}: {subject} belongs at the top level"+ return f"unknown key '{key}' {where}"+++def _config_error_message(path: Path, error: ValidationError) -> str:+ lines = [f"Invalid config file: {path}"]+ for err in error.errors():+ loc = tuple(err.get("loc") or ())+ if err.get("type") == "extra_forbidden" and loc:+ lines.append(f" - {_describe_unknown_key(loc)}")+ elif not loc:+ got = type(err.get("input")).__name__+ article = "an" if got[:1].lower() in "aeiou" else "a"+ lines.append(+ f" - the top level must be a mapping of keys and sections, not {article} {got}"+ )+ else:+ field = ".".join(str(part) for part in loc) or "config"+ lines.append(f" - {field}: {err.get('msg', 'invalid value')}")+ return "\n".join(lines)++def load_config(path: Optional[Path]) -> Config:"""Load config from YAML/JSON file, or return defaults if no path given."""if not path:@@ -137,11 +197,42 @@ def load_config(path: Optional[Path]) -> Config:if not path.exists():raise FileNotFoundError(f"Config file not found: {path}")- text = path.read_text(encoding = "utf-8")+ # utf-8-sig: drops a Notepad BOM, identical to utf-8 when there is none.+ try:+ text = path.read_text(encoding = "utf-8-sig")+ except UnicodeDecodeError as error:+ raise ConfigError(+ f"Could not read config file: {path}\n"+ f" - {error}\n"+ f" - config files must be UTF-8; re-save it as UTF-8 and try again"+ ) from None+ except OSError as error:+ raise ConfigError(f"Could not read config file: {path}\n - {error}") from None+if path.suffix.lower() in {".yaml", ".yml"}:- data = yaml.safe_load(text) or {}+ try:+ data = yaml.safe_load(text)+ except yaml.YAMLError as error:+ raise ConfigError(f"Could not parse config file: {path}\n - {error}") from Noneelse:import json- data = json.loads(text or "{}")-- return Config(**data)+ try:+ data = json.loads(text.strip() or "{}")+ except json.JSONDecodeError as error:+ hint = (+ ""+ if path.suffix.lower() == ".json"+ else (+ f"\n - parsed as JSON because of the '{path.suffix}' extension; "+ f"name it .yaml or .yml for YAML"+ )+ )+ raise ConfigError(f"Could not parse config file: {path}\n - {error}{hint}") from None++ if data is None:+ data = {}++ try:+ return Config.model_validate(data)+ except ValidationError as error:+ raise ConfigError(_config_error_message(path, error)) from Nonediff --git a/unsloth_cli/tests/test_train_config_unknown_keys.py b/unsloth_cli/tests/test_train_config_unknown_keys.pynew file mode 100644index 00000000000..539828e7bfa--- /dev/null+++ b/unsloth_cli/tests/test_train_config_unknown_keys.py@@ -0,0 +1,238 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""`unsloth train --config` used to drop unrecognised keys, so `learning_rate` at the+top level, or a CLI-style spelling inside a section, trained on defaults in silence."""++from __future__ import annotations++import sys+from pathlib import Path++import pytest+import typer+from typer.testing import CliRunner++_REPO_ROOT = Path(__file__).resolve().parents[2]+if str(_REPO_ROOT) not in sys.path:+ sys.path.insert(0, str(_REPO_ROOT))++from unsloth_cli.config import ConfigError, load_config # noqa: E402++_SHIPPED_CONFIGS = _REPO_ROOT / "studio" / "backend" / "assets" / "configs"+++def _write(tmp_path, body: str) -> Path:+ path = tmp_path / "config.yaml"+ path.write_text(body, encoding = "utf-8")+ return path+++def _train_app():+ from unsloth_cli.commands.train import train++ app = typer.Typer()+ app.command()(train)+ return app+++def test_top_level_flat_key_is_rejected_and_names_its_section(tmp_path):+ path = _write(tmp_path, "model: unsloth/Qwen2.5-0.5B\nlearning_rate: 5e-5\n")++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ message = str(excinfo.value)+ assert "learning_rate" in message+ assert "training:" in message+++def test_hyphenated_top_level_key_is_rejected_and_names_its_section(tmp_path):+ path = _write(tmp_path, "learning-rate: 5e-5\n")++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ message = str(excinfo.value)+ assert "learning-rate" in message+ assert "training:" in message+++def test_key_in_the_wrong_section_is_rejected_and_names_the_right_one(tmp_path):+ path = _write(tmp_path, "training:\n lora_r: 8\n")++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ message = str(excinfo.value)+ assert "lora_r" in message+ assert "'training'" in message+ assert "'lora:'" in message+++def test_cli_spelling_inside_a_section_is_rejected_with_the_yaml_spelling(tmp_path):+ path = _write(tmp_path, "training:\n num-epochs: 9\n")++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ message = str(excinfo.value)+ assert "num-epochs" in message+ assert "num_epochs" in message+++def test_valid_config_still_loads(tmp_path):+ path = _write(+ tmp_path,+ "model: unsloth/Qwen2.5-0.5B\n"+ "data:\n"+ " dataset: tatsu-lab/alpaca\n"+ "training:\n"+ " num_epochs: 9\n"+ " learning_rate: 5e-5\n"+ "lora:\n"+ " lora_r: 8\n",+ )++ cfg = load_config(path)++ assert cfg.model == "unsloth/Qwen2.5-0.5B"+ assert cfg.data.dataset == "tatsu-lab/alpaca"+ assert cfg.training.num_epochs == 9+ assert cfg.training.learning_rate == 5e-5+ assert cfg.lora.lora_r == 8++[email protected]("name", ["full_finetune.yaml", "lora_text.yaml", "vision_lora.yaml"])+def test_shipped_example_configs_still_load(name):+ assert load_config(_SHIPPED_CONFIGS / name).model+++def test_train_exits_2_instead_of_tracebacking_on_an_unknown_key(tmp_path):+ path = _write(tmp_path, "model: unsloth/Qwen2.5-0.5B\nlearning_rate: 5e-5\n")++ result = CliRunner().invoke(_train_app(), ["--config", str(path)])++ assert result.exit_code == 2+ assert result.exception is None or isinstance(result.exception, SystemExit)+ assert "learning_rate" in result.output+ assert "training:" in result.output+++def test_unparseable_yaml_reports_cleanly_instead_of_tracebacking(tmp_path):+ path = _write(tmp_path, "training:\n num_epochs: 3\n learning_rate: 1\n")++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ assert "Could not parse config file" in str(excinfo.value)+++def test_unparseable_json_reports_cleanly_instead_of_tracebacking(tmp_path):+ path = tmp_path / "config.json"+ path.write_text("{oops}", encoding = "utf-8")++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ assert "Could not parse config file" in str(excinfo.value)+++def test_a_top_level_list_reports_cleanly_instead_of_tracebacking(tmp_path):+ path = _write(tmp_path, "- model: unsloth/Qwen2.5-0.5B\n- model: unsloth/Qwen2.5-1.5B\n")++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ message = str(excinfo.value)+ assert "must be a mapping" in message+ assert "list" in message+++def test_an_empty_config_still_loads_defaults(tmp_path):+ assert load_config(_write(tmp_path, "")).training.num_epochs == 3+++def test_a_directory_reports_cleanly_instead_of_tracebacking(tmp_path):+ """read_text sits outside the parse handlers, so this escaped as a raw traceback."""+ directory = tmp_path / "config.yaml"+ directory.mkdir()++ with pytest.raises(ConfigError) as excinfo:+ load_config(directory)++ assert "Could not read config file" in str(excinfo.value)+++ ("name", "raw"),+ [+ ("latin1", "model: café\n".encode("latin-1")),+ ("utf16", "model: unsloth/Qwen2.5-0.5B\n".encode("utf-16")),+ ],+)+def test_a_non_utf8_config_reports_cleanly_instead_of_tracebacking(tmp_path, name, raw):+ path = tmp_path / f"{name}.yaml"+ path.write_bytes(raw)++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ message = str(excinfo.value)+ assert "Could not read config file" in message+ assert "UTF-8" in message++[email protected]("suffix", [".yaml", ".json"])+def test_a_byte_order_mark_written_by_notepad_still_loads(tmp_path, suffix):+ """Windows editors prepend a UTF-8 BOM; utf-8-sig drops it, plain utf-8 does not."""+ body = (+ "model: unsloth/Qwen2.5-0.5B\n"+ if suffix == ".yaml"+ else '{"model": "unsloth/Qwen2.5-0.5B"}'+ )+ path = tmp_path / f"config{suffix}"+ path.write_bytes(b"\xef\xbb\xbf" + body.encode("utf-8"))++ assert load_config(path).model == "unsloth/Qwen2.5-0.5B"+++def test_a_whitespace_only_json_config_loads_defaults_like_yaml_does(tmp_path):+ path = tmp_path / "config.json"+ path.write_text(" \n\t\n", encoding = "utf-8")++ assert load_config(path).training.num_epochs == 3+++def test_an_unrecognised_extension_says_it_was_parsed_as_json(tmp_path):+ path = tmp_path / "config.txt"+ path.write_text("model: unsloth/Qwen2.5-0.5B\n", encoding = "utf-8")++ with pytest.raises(ConfigError) as excinfo:+ load_config(path)++ message = str(excinfo.value)+ assert "parsed as JSON" in message+ assert ".yaml" in message+++def test_a_top_level_scalar_reads_grammatically(tmp_path):+ with pytest.raises(ConfigError) as excinfo:+ load_config(_write(tmp_path, "42\n"))++ assert "not an int" in str(excinfo.value)+++ "body",+ [+ "training:\n num_epochs: 3\n learning_rate: 1\n",+ "- model: unsloth/Qwen2.5-0.5B\n",+ ],+)+def test_train_exits_2_on_an_unloadable_config(tmp_path, body):+ result = CliRunner().invoke(_train_app(), ["--config", str(_write(tmp_path, body))])++ assert result.exit_code == 2+ assert result.exception is None or isinstance(result.exception, SystemExit)+ assert result.output.startswith("Error: ")