Skip to content

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.

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.py
index 8b6aac4f21f..2175cf0eccd 100644
--- a/unsloth_cli/commands/train.py
+++ b/unsloth_cli/commands/train.py
@@ -9,7 +9,7 @@ import typer
from unsloth_cli._inference import ensure_studio_backend_path
from unsloth_cli._studio_deps import studio_backend_imports
-from unsloth_cli.config import Config, load_config
+from unsloth_cli.config import Config, ConfigError, load_config
from 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.py
index dbc7701f706..66c3748de99 100644
--- a/unsloth_cli/config.py
+++ b/unsloth_cli/config.py
@@ -5,16 +5,20 @@ from pathlib import Path
from typing import Literal, Optional, List
import yaml
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
class DataConfig(BaseModel):
+ model_config = ConfigDict(extra = "forbid")
+
dataset: Optional[str] = None
local_dataset: Optional[List[str]] = None
format_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 = 2048
load_in_4bit: bool = True
@@ -34,6 +38,8 @@ class TrainingConfig(BaseModel):
class LoraConfig(BaseModel):
+ model_config = ConfigDict(extra = "forbid")
+
lora_r: int = 64
lora_alpha: int = 16
lora_dropout: float = 0.0
@@ -49,6 +55,8 @@ class LoraConfig(BaseModel):
class LoggingConfig(BaseModel):
+ model_config = ConfigDict(extra = "forbid")
+
enable_wandb: bool = False
wandb_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] = None
data: 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 None
else:
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 None
diff --git a/unsloth_cli/tests/test_train_config_unknown_keys.py b/unsloth_cli/tests/test_train_config_unknown_keys.py
new file mode 100644
index 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: ")