Settings Soup refuses at load
A soup.yaml used to be able to ask for one thing and train another: the schema accepted the setting, a validator checked its range, and for most settings nothing on the path it named ever read it (for a few, listed below, what read it did the wrong thing). v0.76.0 refused the settings that never took effect and warned about the ones it still tolerated. v0.77.0 refuses those too, and fourteen of the fifteen settings that, in upstream's list, v0.76 accepted without a word (the fifteenth, a KTO row with a malformed label, is dropped at data load with a reason). This page is the reference for what the load does at v0.77.2 (the refusals themselves are v0.77.0's; v0.77.1 added the MLX GRPO refusals, the unknown-key hints and the plan and apply checks, and v0.77.2 added four settings refused on task: sft paths that never read them, each marked below): how it decides, the refusals grouped by what they touch with the start of each message and what to change (rows that differ only by task or backend are merged), the 31 staged fields, the deprecated values, and the keys that are still unread but not refused.
Unknown keys have refused the load since v0.75.0, and that has not changed. Upstream publishes no count of the other refusals, so neither does this page.
soup doctor --config soup.yamlRun that on every config that loaded on an older release before you train with v0.77. It loads the file with the same rules as soup train, prints the error if the load is refused, and exits 2. Unknown keys are reported together, but a refusal that spans several fields prints only the first one it hits, so fix that setting and run the command again until it prints no error.
How a config loads at v0.77.0
This is the order at v0.77.2 (the steps are unchanged since v0.77.1) and, where nothing is marked, at v0.77.0. soup train and the other commands that build a config from a soup.yaml (soup doctor --config, soup bench, soup cost, soup profile, soup sweep, soup recipes verify --config, soup ship --config and, since v0.77.1, soup plan and soup apply, and the --config forms of some soup eval and soup data commands) call one loader. It does these things in this order:
- The file is read under limits (since v0.76.1, #1827). Every YAML file Soup reads goes through one loader. Nesting is limited to 100 levels, and the document's top-level mapping counts as the first, so 99 levels of brackets under a top-level key is the deepest structure that loads; expansion is limited to one node per source byte plus 10,000 for anchors, aliases and merge keys, with merge keys chained at most 100 levels; and a
soup.yamlmay be at most 1 MiB. A file over a limit, a directory, a file the system will not let Soup read, bytes that are not UTF-8 and a file that is not valid YAML (a syntax error, or a value YAML cannot build, such as a date that does not exist) each stop the load with one line that names the file and the problem, before any key is checked, for exampleConfig file soup.yaml is larger than 1048576 bytes; refusing,Config file soup.yaml nests collections more than 100 levels deep; refusing,Config file soup.yaml expands to more than N nodes from M bytes of YAML; refusing,Config file soup.yaml is not valid YAML: <problem> (line L, column C),Config file soup.yaml is not valid UTF-8: ...andConfig file soup.yaml is a directory, not a file.soup trainexits 1 andsoup doctor --configexits 2. Through v0.76.0 there was no size, nesting or expansion limit, and a syntax error printed the parser's own multi-line message. A hand-written config is kilobytes; what the limits stop is a generated file, or a few hundred bytes of anchors and aliases that describe a structure many times larger. - The file must be a YAML mapping. An empty file prints
Config file is emptyand a list or a bare value printsConfig must be a YAML mapping, got list;soup trainexits 1 on both andsoup doctor --configexits 2. - An unknown key refuses the load. The message has four forms since v0.77.1 (#2099, #2138). A key written the way another library names it gets the Soup field:
unknown config key 'training.learning_rate' - use training.lr. Refused.That covers the Hugging Face and TRL names such aslearning_rate,num_train_epochs, andper_device_train_batch_size(at the top level and undertraining:),grad_accum_stepsandgradient_accumulation(undertraining:only),lr,epochsandbatch_sizewritten at the top level, and a one-edit typo of one of them (training.lerning_rate). A name that is only similar to a declared field getsunknown config key 'x' - did you mean 'y'? Refused., ranked with the same similarity cutoff (0.65) in every section. A Hugging Face name Soup has no setting for (per_device_eval_batch_size,per_gpu_eval_batch_size,eval_batch_size,warmup_steps,warmup_step) gets a sentence saying so, with no replacement field; for warmup it namestraining.warmup_ratio. When no key is close, the message names the key and suggests nothing. The hints are diagnostics: the schema still decides what loads, and nothing is substituted. Through v0.77.0 there were two forms, sotraining.learning_rateread- refused.with no hint. Typos such asearly_stopp_patienceland here, and they are checked before anything else: nothing else is reported until the unknown keys are gone. - The schema validates the values and the combinations. A value out of range, a key that needs another key, a deprecated value and every refusal in the tables below come from this step. A failure prints
Config validation error:and one indented line per problem. A refusal of one field readstraining -> optimizer: <message>; a refusal that spans several fields prints its message alone, or aftertraining:ordata:when it comes from that section's own check. Since v0.77.0 the terminal no longer prints Pydantic'sValue error,prefix in front of a message; the loader that the API and the Web UI use (load_config_from_string) raises aValueErrorwhose text keeps it. - A staged field set away from its default refuses the load (since v0.77.0; v0.76 warned). Each prints
<section>.<name> is accepted but read by nothing; refused as of v0.77. Delete the line., one line per field, ahead of every other error in the same report. When a staged field's own check fails as well (for exampletraining.grace_codebook: truewithout a size and a dimension, ordata.video_fpson a format that is not video), only the staged line is shown, so no message asks you to fix a line that the next load refuses anyway. See The 31 staged fields.
Since v0.77.0 the loader prints no warning of its own. soup train still prints a Note: after the load for five keys that are set but not enforced (see Keys that are still unread and not refused).
| Outcome | soup doctor --config | soup train |
|---|---|---|
| Refused (a file over a read limit, unreadable or not valid YAML; an unknown key; a staged field; a deprecated value; a value or combination below) | prints the error, then Config could not be loaded (see above)., exits 2 | prints Config validation error: (or the read-limit line) and exits 1, before it imports the training stack |
| Loads | exits 0 | trains |
soup recipes verify --config and soup ship --config exit 3 on a refused config (Config does not parse: ...; Error: --config: ...). Since v0.77.1 (#2242) soup plan and soup apply refuse what soup train refuses: they run the same checks, print the same Config validation error: lines and exit 1, write no plan and leave an existing state file unchanged. At v0.77.0 they were the exception to the table: they read the YAML under the read limits and ran the unknown-key check only, so soup plan --config wrote a plan for a config that soup train refused. The other YAML readers apply the same nesting and expansion limits with their own size caps, and report a refusal through their own handlers: soup plan and soup apply exit 2 on a limit and, since v0.77.2 (#2323), on a syntax error and on a config they cannot read too, with a message that names the config and the YAML location (Config 'soup.yaml' is not valid YAML: ... (line L, column C); through v0.77.1 a syntax error exited 1 with the parser's own error, and a missing file is still 1: Config not found: ...), soup eval gate exits 3 on a suite over a limit and, since v0.77.1, on a syntax error too (it exited 1 through v0.77.0; soup train --gate exits 1 on either), and soup ship --config reads up to 4 MiB and exits 3. Configuration lists the caps and Exit codes the codes.
Here is a config that loaded on v0.76 with two warnings and is refused at v0.77.0. The keys are real, they validate, and nothing reads them (this fence shows a refusal on purpose):
base: org/model
task: sft
data:
train: ./data.jsonl
training:
early_stop_patience: 3
lr_groups:
- pattern: ".*lora_A.*"
lr: 0.001Config validation error:
training.lr_groups is accepted but read by nothing; refused as of v0.77. Delete the line.
training.early_stop_patience is accepted but read by nothing; refused as of v0.77. Delete the line.soup train --config exits 1 on it and soup doctor --config exits 2. A field is refused only when its value differs from the schema default, so early_stop_patience: 2 loads and 3 is refused. Rich wraps these lines to the width of your terminal.
What to do with a refusal. Remove the key, or change it as the message says. Deleting the key is the fix. For a staged field it changes no result, because none of them changed what a run did. For most other rows below, the setting was not read, or the run stopped after the model had loaded. A few keys are different: on v0.75, training.use_longlora: true, training.ebft_variant and training.quantization_aware: true WERE applied, wrongly, and Re-run this on the v0.76.0 release page lists them; the v0.77.0 ones (for example ReLoRA on a loss with a frozen reference, and LLaMA Pro with a LoRA rank) are on the v0.77.0 release page. Renaming a key does nothing useful: these settings were read or ignored, not misspelled. A config that has to load on both v0.76 and v0.77 needs the key removed. Configs Soup itself wrote on v0.75 or earlier (soup autopilot output and run-config dumps) can carry data.remove_unused_columns: true or training.quantization: 4bit on a task that never quantizes; delete those lines.
Settings that are refused
Each row was checked against the loader and the validators at the v0.77.0 tag, and the messages were probed on the v0.77.0 binary; the rows and messages marked v0.77.1 were probed on the v0.77.1 binary. The third column is the exact start of the message, which always goes on to say what to change; the fourth column is that advice in short. Pull request numbers are upstream's. Where one setting is refused in several task or backend combinations the rows are merged. Rows and conditions new in v0.77.0 say so.
Variants and modes that never ran
| Setting | Refused when | Message begins | What to change |
|---|---|---|---|
training.ebft_variant, training.ebft_temperature | ebft_variant has any value (#1230); ebft_temperature alone is refused too | training.ebft_variant is refused (#1230): EBFT is not yet a distinct objective. | Remove both keys |
training.gdpo_variant | any value (#1309) | training.gdpo_variant is refused (#1309): supported TRL versions do not expose the dpo_loss hook, so this setting was accepted but ignored. | Remove it and use plain task: dpo |
training.quantization_aware | true (#1222) | training.quantization_aware: true is refused (#1222): int8 quantization-aware training is not implemented. | Remove it. fp8 and quest take other code paths and are not refused here |
training.use_longlora | true (#1240) | training.use_longlora: true is refused (#1240): the current LongLoRA implementation leaks future tokens and is not S^2 shifted sparse attention. | Set training.rope_scaling_type (linear, dynamic, yarn or llama3) and train plain LoRA |
training.rope_scaling_type | longrope (#1239) | training.rope_scaling_type='longrope' is refused (#1239): it cannot extend any checkpoint. | Choose another rope_scaling_type |
training.kernel_auto_compose | true (#801) | kernel_auto_compose is not supported: it benchmarks the same already-loaded model for every candidate and does not apply the selected flags. | Set it to false and turn on use_liger or use_flash_attn yourself |
training.quantization | bitnet_1.58 (#825, #981) | BitNet 1.58 training is not implemented yet; | Export an existing BitNet checkpoint instead |
training.tts_family with data.format: audio | spark or oute (#265) | TTS family 'spark' has no installable 'sparktts' PyPI package. | Pre-encode the audio outside Soup and train with data.format: chatml; the message gives the reason for each family |
training.use_mod | true on a route that never installs a Mixture-of-Depths router (new in v0.77.0, #1752): a task other than sft, tts or pretrain; on sft or tts, backend: mlx or unsloth, modality: vision or audio, stream_layers: true, unfrozen_parameters, lisa_enabled or lora.r: 0; on pretrain, backend: unsloth | training.use_mod is not applied by task='dpo': only task='sft', 'tts' and 'pretrain' install a Mixture-of-Depths router, so this run would train without one. | Use a route that installs it, or set use_mod: false |
training.tts_family: sesame_csm | with a data.format other than audio, a backend other than transformers, quantization other than none, or a setting the native trainer does not apply (#1769). Through v0.76.1 every sesame_csm config was refused; since v0.77.0 Sesame CSM trains through a native trainer | Sesame CSM requires training.quantization='none' / Sesame CSM does not support training.tts_emotion | Use data.format: audio, write quantization: none (the schema default 4bit is refused) and only the settings listed on Modality II |
Context length and block expansion
| Setting | Refused when | Message begins | What to change |
|---|---|---|---|
training.rope_scaling_type | task is not sft, tts or pretrain; or the run is on backend: mlx or unsloth, modality: vision or audio, or stream_layers: true (#1697); the yarn_* keys set beside rope_scaling_type are named in the same message | training.rope_scaling_type is not applied by task='dpo': only task='sft', 'tts' and 'pretrain' rescale RoPE, so this run would train on the checkpoint's own RoPE. | Use one of those tasks on the text path with backend: transformers and no layer streaming, or remove the key |
training.freeze_trainable_layers | set without expand_layers (#1396) | freeze_trainable_layers only applies together with expand_layers (LLaMA Pro block expansion), where it must equal expand_layers and trains only the appended blocks. | Remove it, or set expand_layers as well |
training.freeze_trainable_layers | differs from expand_layers (#1409) | freeze_trainable_layers: 32 does not match expand_layers: 4. | Set both to the same number |
training.expand_layers | set without freeze_trainable_layers (refused before v0.76.0 as well) | expand_layers requires freeze_trainable_layers (LLaMA Pro freezes the original layers and trains only the new blocks). Set freeze_trainable_layers: 4. | Set freeze_trainable_layers to the same number as expand_layers |
training.expand_layers | quantization is not none (#1237, #1308) | training.expand_layers (LLaMA Pro block expansion) requires training.quantization: none, but it is '4bit'. | Set quantization: none |
training.expand_layers | the task is not sft, the backend is not transformers or the modality is not text (#1325; task: pretrain is refused too since v0.77.0, #1875) | training.expand_layers (LLaMA Pro) only trains the appended blocks on task sft with backend transformers and modality text; got task='dpo', backend='transformers', modality='text'. | Remove expand_layers and freeze_trainable_layers; on pretrain the message points at task: sft with lora.r: 0 |
training.expand_layers | with a LoRA rank, lora.r of 1 or more (new in v0.77.0, #1783) | training.expand_layers: 4 with training.freeze_trainable_layers: 4 (LLaMA Pro) cannot be combined with LoRA (training.lora.r: 64). | Set lora.r: 0 with quantization: none, the route that trains the new blocks |
Adapters
| Setting | Refused when | Message begins | What to change |
|---|---|---|---|
training.loraplus_lr_ratio | combined with optimizer: apollo_adamw, lomo or adalomo (#1210) | training.loraplus_lr_ratio cannot be combined with training.optimizer='apollo_adamw': | Use an optimizer transformers can build without the model |
training.loraplus_lr_ratio | combined with use_galore: true (#1210) | training.loraplus_lr_ratio and training.use_galore are mutually exclusive: | Enable one |
training.loraplus_lr_ratio | backend: mlx (#1324) | Refused: training.loraplus_lr_ratio is not implemented on backend='mlx' | Remove it, or use backend: transformers |
training.loraplus_lr_ratio | no LoRA B matrix trains: prm, unlearn, moe_lora_routing, classifier, reranker or cross_encoder without classifier_lora, asr without asr_lora, or lora.use_vera; each message names its own reason (#745) | Refused: training.loraplus_lr_ratio needs a trainable LoRA adapter. task='prm' is a full fine-tune with no LoRA adapter, | Remove it for that task, or set training.classifier_lora: true (or training.asr_lora: true for asr) |
training.use_lorafa | combined with loraplus_lr_ratio (#725) | training.use_lorafa and training.loraplus_lr_ratio are mutually exclusive: | Enable one |
training.use_lorafa | task other than embedding, pretrain or sft; or backend is not transformers (#725) | training.use_lorafa (LoRA-FA optimizer) is currently only supported for tasks embedding, pretrain, sft; got task='dpo' | Use a supported task and backend: transformers |
training.use_lorafa | optimizer: adamw_bnb_8bit (#725) | training.use_lorafa uses an AdamW-based gradient projection and is incompatible with training.optimizer='adamw_bnb_8bit'. | Leave optimizer unset or use adamw_torch |
training.lora.use_dora, use_vera, init_strategy | a variant (dora, vera, or an init_strategy other than random) on backend: unsloth, or VeRA or a non-random init_strategy on backend: mlx (#1037) | training.lora variant 'dora' requires backend='transformers'; backend='unsloth' has its own adapter constructor and cannot apply this PEFT method. | Use backend: transformers or plain LoRA |
training.lora.use_dora | on backend: mlx outside text sft with quantization none or 4bit, or beside lora.use_rslora, rank_pattern or alpha_pattern (MLX SFT trains DoRA natively since v0.77.0, #1918) | MLX DoRA requires task='sft', modality='text' and quantization='none' or '4bit'. / MLX DoRA does not support lora.use_rslora, rank_pattern or alpha_pattern; | Use MLX SFT with scalar lora.r and lora.alpha, or backend: transformers |
training.lora.use_dora, use_vera, init_strategy | a variant on task: moe_lora_routing (#1037) | training.lora variant 'dora' is not applied by task='moe_lora_routing': that trainer loads existing adapters with PeftModel.from_pretrained instead of constructing a new adapter. | Keep the defaults and configure the adapters through training.mole_task_adapters |
training.lora.use_dora | quantization is gptq, awq, aqlm or eetq (#1466) | training.lora.use_dora=True is not supported with training.quantization='gptq': peft cannot apply DoRA to aqlm, awq, eetq, gptq layers and raises when the adapter is attached, after the model has loaded. | Set use_dora: false, or use a 4bit, 8bit, hqq:Nbit or unquantized base |
training.lora.init_strategy | pissa or loftq with quantization other than none (#1037) | training.lora.init_strategy='pissa' requires training.quantization='none': | Set quantization: none |
training.lora.rank_pattern, training.lora.alpha_pattern | backend: mlx (#1996) or backend: unsloth (#2153), new in v0.77.0 (both backends ignored the pattern before). An empty {} loads | training.lora.rank_pattern is not applied by backend: mlx — the MLX trainer builds every adapter from one scalar training.lora.r and training.lora.alpha, | Remove the pattern, or use backend: transformers |
training.lora | task: prm with a lora block that differs from the schema default, unless lora.r: 0 (#795) | task='prm' does not apply training.lora: the PRM trainer fine-tunes every base parameter. | Remove the lora block, or set lora.r: 0 |
training.lora.r | 0 on task: pretrain (new in v0.77.0, #1875) | training.lora.r=0 (full fine-tuning) is not supported with task='pretrain': its trainer always attaches a LoRA adapter, | Use lora.r of 1 or more, or task: sft with lora.r: 0 |
training.relora_steps | quantization is not explicitly none (#693) | relora_steps requires quantization='none' (got '4bit'); ReLoRA restart merges into the base weight, which requires a writable float base. | Set quantization: none |
training.relora_steps | with lora.use_dora: true, use_fsdp2_compile: true or stream_layers: true (#693), or on backend: mlx | relora_steps is incompatible with lora.use_dora=True: / relora_steps is not supported on the mlx backend (callback is HF Trainer-specific). | Drop one of the two |
training.relora_steps | the loss compares the policy with a frozen reference (new in v0.77.0, #1891): dpo, ipo, kto, bco, grpo with grpo_beta above 0, or preference whose loss or blend names dpo, ipo or bco | training.relora_steps cannot be used here (task='dpo'): the loss compares the policy with a frozen reference, which trl builds on the policy's own base weights | Remove relora_steps (or the term from preference_loss_weights); sft, orpo, simpo and grpo with grpo_beta: 0 keep ReLoRA |
training.moe_lora | task: asr (#1151), modality: vision or audio (#1179), backend: unsloth (#1264) | training.moe_lora is not applied by task='asr': that trainer loads Whisper, which has no expert layers. | Remove it, or use the text sft path on backend: transformers |
training.moe_aux_loss_coeff | a value other than the default 0.01, on a task other than sft, tts or pretrain (#798), on task: sft with modality: vision or audio (#1394), and since v0.77.0 on backend: unsloth or with stream_layers: true (#1749). moe_expert_quant and train_router_only are refused on any task other than sft and tts (#798) | training.moe_aux_loss_coeff=0.05 is not applied by task='dpo': / training.moe_aux_loss_coeff=0.05 is not applied on backend='unsloth': that setup never applies the MoE auxiliary loss. / training.moe_aux_loss_coeff=0.05 is not applied with training.stream_layers: | Remove it, or use a route that reads it |
Optimizers
The allowlist is 24 names (v0.76.0 cut it from 32). The checks apply to training.optimizer (#1269, #1283).
| Setting | Refused when | Message begins | What to change |
|---|---|---|---|
training.optimizer | adam_mini, adamw_apex_fused, ao_adamw_4bit, ao_adamw_8bit, ao_adamw_fp8, badam, came_pytorch or dion | optimizer='badam' is no longer supported: transformers 5.x rejects it in TrainingArguments after the model has loaded, so Soup refuses it at config load instead. | Use adamw_torch, adamw_torch_fused, adamw_bnb_8bit, adafactor or another name from the 24-name allowlist |
training.optimizer | muon or adamw_hf on any backend except mlx | training.optimizer='muon' only works on backend: mlx (the MLX backend builds it itself); | Switch to backend: mlx, or use a supported optimizer |
Quantization
| Setting | Refused when | Message begins | What to change |
|---|---|---|---|
training.quantization (or load_in_8bit: true) | 4bit or 8bit written explicitly on distill, classifier, reranker, cross_encoder, prm, moe_lora_routing, unlearn or asr (since v0.77.0; v0.76 warned, #795) | training.quantization: 4bit has no effect on task='distill': its trainer never quantises the base, so no run can honour it. (it ends Refused as of Soup v0.77.) | Delete the line or set quantization: none; for load_in_8bit: true, delete it and any quantization line. Unset resolves to none. On backend: unsloth or mlx the message also names the backend's fix |
training.quantization | gptq, awq or another Quant Menu value on those same eight tasks (#795) | task='distill' does not apply training.quantization: its trainer never quantises the base, so quantization='gptq' would record a quantised run that never happens. | Remove it, or set quantization: none |
training.quantization | 8bit with backend: unsloth (new in v0.77.0, #1946) | training.quantization: 8bit is not applied on backend: unsloth (Soup's Unsloth loader passes load_in_4bit only, so 8bit loaded the model in 16-bit). | Use 4bit or none on Unsloth, or backend: transformers for 8-bit |
training.bnb_4bit_quant_storage | quantization is not 4bit (#1466) | bnb_4bit_quant_storage='uint8' requires quantization '4bit', got 'mxfp4'. | Use quantization: 4bit, or remove the key |
training.bnb_4bit_quant_storage | set on distill, classifier, reranker, cross_encoder, prm, moe_lora_routing, unlearn or asr (#795) | task='distill' does not apply training.quantization: its trainer never quantises the base, so quantization='4bit' would record a quantised run that never happens. | Remove the key, or set quantization: none |
training.quantization_aware: fp8 | backend: unsloth (#1124) | v0.28.0 features ['quantization_aware="fp8"'] are not supported on the unsloth backend (unsloth uses its own fused kernels). | Use backend: transformers, or remove the flag |
Task and backend scope
| Setting | Refused when | Message begins | What to change |
|---|---|---|---|
backend: unsloth | task is outside sft, dpo, grpo, ppo, kto, orpo, simpo, ipo, bco, preference, pretrain, embedding and tts (#1357) | backend='unsloth' is not applied by task='classifier': that trainer has no unsloth setup and would train on plain transformers. | Use backend: transformers |
backend: unsloth | task: dpo with modality: vision (#1393) | task='dpo' with modality='vision' requires backend='transformers': | Use backend: transformers |
backend: unsloth | task: sft with modality: vision or audio (new in v0.77.0, #2015; those runs loaded through transformers and did not use Unsloth) | task='sft' with backend='unsloth' requires modality='text': | Use backend: transformers for multimodal SFT |
backend: mlx | a task other than sft, dpo, orpo, simpo, kto and grpo (the four preference tasks train natively on MLX since v0.77.0 and grpo since v0.77.1; since v0.77.2 task: preference with training.preference_loss dpo, orpo or simpo runs the native trainer of that name too, #2333 by @vaputa, while task: preference with ipo or bco and any preference_loss_weights blend stay refused; covered only by the hosted macOS MLX test job and not exercised by hand before the release) | MLX backend only ships SFT, DPO, ORPO, SimPO, KTO and GRPO; task='ppo' has no trainer on backend='mlx'. (through v0.77.0: ... SFT, DPO, ORPO, SimPO and KTO; task='grpo' has no trainer ...) | Use task: dpo, orpo or simpo on MLX for a preference run (since v0.77.2 also task: preference with one of those three losses), or backend: transformers |
training.*, modality, grpo_variant on task: grpo with backend: mlx (new in v0.77.1, #2182) | a modality other than text; training.lora.r: 0; training.quantization: 8bit; a training.reward_fn other than the built-in accuracy or format (a comma-separated ensemble, verifiable, judge_rank or a custom reward file); training.grpo_variant; prm_reward; rollout_backend and rollout_func; tis_threshold, off_policy_mask_threshold, mask_truncated_completions, skip_zero_advantage, async_grpo_prefetch, replay_buffer_size, defer_rerolling, grpo_fp16 and ref_model_ema_alpha; every reward_hack_*, echo_trap_*, rl_checkpoint_* and curriculum* setting; eval_steps; use_dora; loss_watchdog; relora_steps; use_liger; use_flash_attn; neftune_alpha; lora.rank_pattern and alpha_pattern; multipack; stream_layers. The training settings the schema lists for this task are refused only when set away from their default | training.eval_steps is not applied by task='grpo' on backend='mlx': MLX GRPO scores the validation split once, after training (val_reward), with no mid-run evaluation. Remove training.eval_steps, or use backend: transformers. / training.reward_fn='./my_reward.py' is not supported by task='grpo' on backend='mlx': MLX GRPO does not load custom reward files; / grpo_variant is not supported on backend=mlx: MLX GRPO trains TRL's default objective (loss_type='dapo') only. | Remove the setting, use a built-in reward, or use backend: transformers. data.chat_template, lora.use_rslora and grpo_beta (0 included) load. See GRPO on MLX |
training.lora.r, modality, training.quantization on MLX preference tasks | dpo, orpo, simpo or kto on backend: mlx with lora.r: 0, a modality other than text, or (on orpo, simpo and kto) quantization: 8bit (new in v0.77.0, with the trainers) | training.lora.r must be at least 1 for task='dpo' on backend='mlx': / modality='vision' is not supported by task='dpo' on backend='mlx': / training.quantization='8bit' is not supported by task='orpo' on backend='mlx': | Use LoRA, text rows, and quantization: none or a pre-quantized mlx-community 4-bit base with quantization: 4bit |
modality: vision or audio | task: distill (new in v0.77.0, #2014) | task='distill' requires modality='text': the distill trainer loads a text-only student and teacher | Use modality: text |
base | a known Kimi K2 Hub id (moonshotai/Kimi-K2-Base, -Instruct, -Instruct-0905, -Thinking) loaded resident (new in v0.77.0, #2104) | Resident Kimi K2 is unsupported on Transformers 5.x. | For Base and Instruct, training.stream_layers: true (the message names it, with --trust-remote-code and pip install tiktoken); Instruct-0905 and Thinking have no supported route. See Streaming a Mixture-of-Experts base |
training.use_liger, training.use_flash_attn | task is not sft or tts (#806); and, new in v0.77.2, on task: sft with backend: unsloth, modality: vision or modality: audio (#2278, see the four settings on five paths) | training.use_liger=true requires task in ['sft', 'tts']; got task='dpo' | Remove it, or use task: sft on the text path with backend: transformers |
training.auto_mixed_precision | task is not sft or tts (#1618) | training.auto_mixed_precision=true is not applied by task='dpo': only task in ['sft', 'tts'] picks bf16/fp16 from the model and GPU | Remove it, or set precision explicitly |
training.reward_fn: judge_rank | a task other than grpo, or no training.grpo_judge or no training.grpo_judge_max_calls (new in v0.77.0; the judge URL is checked at load: ollama://, https:// to a host that is not a private, link-local or reserved IP literal, or http:// to loopback) | training.reward_fn judge_rank needs task='grpo' / training.reward_fn judge_rank needs training.grpo_judge, the judge URL / training.reward_fn judge_rank needs training.grpo_judge_max_calls, the most judge calls the run may make: | Set both keys on a grpo run, or use another reward_fn |
training.fast_lora: true | lora.dropout is not 0, which includes the default 0.05 (new in v0.77.0) | training.fast_lora needs lora.dropout: 0; got 0.05 (Soup's default is 0.05). | Set lora.dropout: 0, or remove fast_lora |
training.freeze_layers, training.freeze_ratio | task is not sft or tts (#1497), or the run is on backend: mlx or unsloth, modality: vision or audio, or stream_layers: true (#1581) | training.freeze_layers is not applied by task='dpo': only task='sft' (and 'tts', which trains through the SFT trainer) freezes layers, so this run would train every layer. | Use the text sft path on backend: transformers with no layer streaming, or remove the key. With LoRA, some target shapes are refused when the model is built: see Refused later than config load |
training.neftune_alpha | any value, 0.0 included, on a task other than sft, tts, dpo, ipo, kto, orpo, simpo, bco and preference (new in v0.77.0, #1883) | training.neftune_alpha=5.0 is set, but task='grpo' never applies it (any value, including 0.0, is refused). | Remove it, or use one of those tasks |
training.reasoning_effort, training.train_on_eot | a task other than sft, tts and distill (since v0.77.0, #806; through v0.76.1 tts was refused and pretrain, classifier, reranker and cross_encoder loaded); and, new in v0.77.2, on task: sft with modality: vision, modality: audio, backend: mlx or data.format: raft, and reasoning_effort with data.format: pre_tokenized (#2278, see the four settings on five paths) | training.reasoning_effort='high' requires task in ['distill', 'sft', 'tts']; got task='pretrain'. | Use sft, tts or distill, or remove it |
training.citation_faithful | a data.format other than raft, or a task other than sft (pretrain is refused too since v0.77.0, #1843) | training.citation_faithful=true requires data.format='raft'; / training.citation_faithful=true requires task='sft'; got task='pretrain'. | Use task: sft with data.format: raft |
training.batch_size | task: kto with batch_size: 1 (#1420) | task='kto' requires training.batch_size >= 2: TRL's KL term is degenerate at a per-device batch of 1. | Set batch_size to 2 or more and raise gradient_accumulation_steps |
training.batch_size | task: embedding with the default contrastive loss at batch_size: 1 (#1234) | contrastive in-batch negatives need batch_size >= 2; use triplet (with negatives) or cosine for batch 1 | Raise batch_size, or choose another embedding loss |
training.dpo_ref_regen_epochs | lora.r: 0 on task: dpo, ipo or preference (#1345); the key is itself accepted only on those tasks (preference with preference_loss dpo or ipo) | dpo_ref_regen_epochs requires LoRA (lora.r >= 1): | Use LoRA, or remove the key |
training.minillm_teacher_mix_ratio | minillm_enabled with minillm_on_policy: false and a ratio of 0 (#692) | minillm_enabled with minillm_on_policy=false requires minillm_teacher_mix_ratio > 0; | Set the ratio in (0, 1], or set minillm_on_policy |
training.distill_chunk_size | outside task: distill, with minillm_enabled, or below 1 (#722) | Distillation fields ['distill_chunk_size'] require task='distill'; got task='sft' | Use task: distill without MiniLLM, and a chunk size of 1 or more |
training.grpo_beta | a boolean (#1247) | grpo_beta must not be a boolean | Give a number; 0 runs KL-free |
training.loss_watchdog, training.loss_spike_recovery, training.grad_accum_auto_tune | true on task: prm, moe_lora_routing or unlearn (#802). On backend: mlx: loss_spike_recovery and grad_accum_auto_tune on every task, and loss_watchdog on every task except text sft (MLX SFT runs the watchdog natively since v0.77.0) | training.loss_watchdog is not supported for task='prm' because 'prm' does not attach a live training callback / training.loss_watchdog is not supported for backend='mlx' because the native watchdog supports only MLX text SFT | Remove it for that task or backend |
training.eval_steps | not an integer (#1223) | training.eval_steps must be an int, not a bool | Give an integer number of optimizer steps |
training.eval_steps | data.val_split is 0 and no source carries its own validation split (#1223) | training.eval_steps is set, but there is nothing to evaluate: | Set data.val_split above 0, or remove eval_steps |
training.eval_steps | task is ppo, online_dpo or unlearn (#1223), or dpo, orpo, simpo or kto on backend: mlx (MLX SFT honours it since v0.77.0, counted in optimizer updates, #1990), or grpo on backend: mlx (since v0.77.1, see the MLX GRPO row above) | training.eval_steps is not supported for task='ppo' because TRL's PPO loop never calls evaluate(); / training.eval_steps is not supported for task='dpo' on backend='mlx': only task='sft' honours it there (#1990); | Remove it; the MLX preference loop evaluates once per epoch, and MLX GRPO scores the validation split once, after training |
Data
| Setting | Refused when | Message begins | What to change |
|---|---|---|---|
data.add_new_tokens, data.new_special_tokens | task is pretrain, embedding, ppo, reward_model, prm, classifier, reranker, cross_encoder, unlearn, moe_lora_routing, distill or asr; or backend is mlx or unsloth (SFT's vision and audio paths on unsloth excepted); or stream_layers: true (#1358) | data.add_new_tokens is not applied by task='pretrain': that trainer never adds tokens to its tokenizer or resizes its embeddings. | Remove it, or use backend: transformers with a task that adds tokens, such as sft or dpo |
data.add_new_tokens | with data.format: pre_tokenized | format='pre_tokenized' cannot be combined with data.add_new_tokens; soup data preprocess never applies it, so the cached ids do not contain it. | Remove it, or train from the source format |
data.format: pre_tokenized | with modality: vision | data.format='pre_tokenized' cannot be combined with modality='vision'; | Train from the source format |
data.chat_template | task is pretrain, embedding, classifier, reranker, cross_encoder, prm, asr, moe_lora_routing or unlearn (#804) | data.chat_template is not used by task='pretrain'; remove it or choose a conversational training task | Remove it |
data.chat_template | backend: mlx, except task: grpo, whose MLX loop applies it (new in v0.77.0, #2051; the MLX trainer ignored it) | data.chat_template is not applied by backend: mlx — the MLX trainer renders the model's shipped template only. | Remove it, or use backend: transformers |
data.mask_history | true with train_on_responses_only: false (#761) | data.mask_history requires data.train_on_responses_only: true | Set train_on_responses_only: true, or drop mask_history |
data.format: llava, sharegpt4v | on dpo, ipo, simpo, orpo, bco or preference (new in v0.77.0, #2064; those runs failed after the model loaded) | task='dpo' with data.format='llava' has no vision-preference row path; use a text preference format instead. | Use a text preference format |
A KTO row whose label is not a boolean, a true/false string or the integer -1, 0 or 1 is not a config refusal. Since v0.77.0 such a row is dropped when the data loads, with KTO label must be a bool, true/false string or -1/0/1 integer, got: 0.5, and the run goes on with the other rows (#2126); soup train exits 1 only when no row is left. soup data validate --format kto counts the dropped rows, prints the reasons for the first three (then ... and N more) and still exits 0 while some rows are valid, unless you pass --min-valid-fraction. See Data formats.
Layer streaming
The streaming checks run on training.stream_layers: true. The full streaming reference is Layer streaming, Layer streaming disk tier and Streaming a Mixture-of-Experts base.
| Setting | Refused when | Message begins | What to change |
|---|---|---|---|
any of training.stream_source, stream_ngram_source, stream_buffers, stream_read_ahead, stream_vram_override, stream_vram_probe, stream_nf4_scale_cache, stream_recompute, stream_expert_layout, stream_disk_kind, stream_pin, stream_loss_chunk | set away from its default while stream_layers is false | training.stream_buffers / training.stream_recompute set but stream_layers is false; (the message names only the keys you set) | Set stream_layers: true, or remove the keys |
training.stream_read_ahead | stream_source: ram (#971) | training.stream_read_ahead=4 has no effect with training.stream_source='ram': the read-ahead reader belongs to the NVMe disk tier, and 'ram' never falls back to it. | Set stream_source: auto or disk, or drop the key |
training.stream_read_ahead | above 8 (#971) | training -> stream_read_ahead: Input should be less than or equal to 8 | Use 8 or less |
training.batch_size: auto | with stream_layers: true, including when batch_size is left unset (its default is auto) | training.stream_layers cannot use batch_size='auto': the probe sizes a RESIDENT model, which a streaming run never loads. | Set a concrete batch_size |
training.use_cut_ce | true with stream_layers: true (new in v0.77.0, #2023: the streamed setup never installed the patch) | training.stream_layers cannot be combined with training.use_cut_ce: the streamed setup never installs the resident Cut Cross-Entropy patch. | Set use_cut_ce: false, or train resident |
training.use_liger, use_flash_attn, nvfp4, quantization_aware | under stream_layers (#1692, #1124) | training.stream_layers is mutually exclusive with use_liger: streaming owns the model-construction path (meta skeleton + per-layer weight substitution) | Turn off one of the two |
training.moe_aux_loss_coeff | a value other than the default (new in v0.77.0, #1749) | training.moe_aux_loss_coeff=0.05 is not applied with training.stream_layers: that setup never applies the MoE auxiliary loss. | Remove it, or train without stream_layers |
training.stream_loss_chunk | a task other than sft, data.format: raft, or beside use_cut_ce (new in v0.77.0, #1880) | training.stream_loss_chunk supports task='sft' only; got task='dpo'. / training.stream_loss_chunk cannot be combined with data.format='raft': | Remove stream_loss_chunk |
training.stream_recompute | off or auto with a task other than sft, or beside activation_offloading (new in v0.77.0, #2152) | training.stream_recompute='off' supports task='sft' only; got task='dpo'. / training.stream_recompute='off' cannot be combined with training.activation_offloading='cpu': | Remove it or set it to on |
training.stream_expert_layout | per_expert with moe_lora (new in v0.77.0, #2029) | training.stream_expert_layout='per_expert' streams the routed experts one at a time and cannot train adapters on them; | Unset moe_lora and adapt attention or the shared expert, or use fused |
training.stream_nf4_scale_cache | without quantization: 4bit and double quantization (new in v0.77.0, #1892) | training.stream_nf4_scale_cache needs quantization='4bit' with double quantization | Set quantization: 4bit and leave bnb_4bit_use_double_quant unset or true, or remove the key |
A LoRA target on lm_head or embed_tokens under stream_layers is no longer a config-load refusal, and since v0.77.1 it is not refused later either, except that a trainable output head (a LoRA target on lm_head) is still refused under stream_loss_chunk (next section). training.use_mod: true under stream_layers is in the use_mod row above. The streaming keys new in v0.77.0 are documented on Layer streaming and Streaming a Mixture-of-Experts base.
task: sft, four settings, five paths (v0.77.2)
task: sft is several code paths. The vision and audio setups, RAFT, a pre-tokenized cache, the MLX trainer and the Unsloth backend each loaded training.reasoning_effort, training.train_on_eot, training.use_flash_attn and training.use_liger and applied some of them or none, so a run trained without a setting the config named. Since v0.77.2 (#2278, by @abdulwaarith0) the config is refused at load, with the field, the setting that selects the path and what to change. Upstream's table of what is refused when the key is set (leave a key out and it loads; the details of false and null are below the table):
| Path | Refused when set |
|---|---|
modality: vision or modality: audio | reasoning_effort, train_on_eot, use_flash_attn, use_liger |
backend: mlx | reasoning_effort, train_on_eot (use_flash_attn and use_liger still load, but soup train stops on them before the MLX trainer starts: CUDA-only checks, exit 1) |
backend: unsloth | use_flash_attn, use_liger |
data.format: raft | reasoning_effort, train_on_eot |
data.format: pre_tokenized | reasoning_effort (train_on_eot loads: the cache is keyed on it) |
stream_layers: true and the other tasks are unchanged. Run on the v0.77.2 binary, the messages read like this, one group per run:
Config validation error:
training.use_flash_attn is not applied by task='sft' with backend='unsloth': the unsloth setup loads its own model, with no Liger patch and no attn_implementation, so this run would ignore it. Use backend: transformers, or remove the key.Other rows read training.reasoning_effort is not applied by task='sft' with backend='mlx': the MLX trainer has its own loop, with no SFT formatter, so this run would ignore it. Use backend: transformers, or remove the key. and, for a vision or audio setup, ... the vision setup builds its own dataset and model, running neither the SFT formatter nor the resident kernel setup ... Use modality: text, or remove the key. For data.format: raft and pre_tokenized the advice is Use data.format: chatml, or remove the key. soup train exits 1 and soup doctor --config exits 2. If two groups apply, the first one it finds is reported and you fix it and run again.
Two details of the values. Leave the key out. The three boolean keys (use_flash_attn, use_liger, train_on_eot) also load when set to false, while null is not a boolean and stops the load with Input should be a valid boolean. reasoning_effort is an optional level, so it loads when it is null, and false does not: a boolean there stops the load with reasoning_effort must not be bool, got False (checked on the v0.77.2 binary; the upgrade notes' shorter sentence, "a value of false or null loads", is not true for every key). And in upstream's words, 0.77.1 "loaded them and trained without them": a run that finished on 0.77.1 trained without the setting its config named, and upstream's notes list no re-run for it. Delete the key, or move the run to the path the message names. A soup.yaml that loaded on v0.77.1 and sets one of these four on one of these paths is, in upstream's upgrade notes, the only kind of file that loaded on 0.77.1 and stops loading on 0.77.2, and soup doctor --config soup.yaml finds it.
Refused later than config load
soup train --dry-run and soup doctor --config pass these, because the check needs the model or the trainer:
- (Since closed in v0.77.1, #2159: a LoRA target on the streamed
embed_tokensorlm_headof an untied checkpoint is accepted now, and the adapter saves and resumes; the message below no longer exists. At v0.77.0 it was refused when the streamed model was built, before a streaming buffer was allocated:training.stream_layers does not yet support a LoRA target on the streamed lm_head of an untied checkpoint:, #2082. On a tied checkpoint it trained and saved. Through v0.76.1 this was a config-load check on the literal names only.) See Layer streaming for what the accepted case needs. training.freeze_layersorfreeze_ratiounder LoRA with a target peft cannot restrict by layer: a stringlora.target_modules(a regular expression,all-linear, or whatautoresolves to on some architectures),lora.target_parameters,lora.use_vera, a list naming a module outside the decoder layers, or a plan that freezes every layer, refused when the model is built (training.freeze_layers / training.freeze_ratio cannot currently be combined with a string training.lora.target_modules, #2145).- a
preference_loss_weightsblend with adpooripoterm under asimpoororpoprimary, together withlora.init_strategypissa,oloraorloftq, refused at trainer setup before the model loads (#1828). The same blend withrelora_stepsis refused at config load instead (#1891, therelora_stepsrow above). Abcoterm in a blend is still refused at trainer setup. task: ppowithreward_hack_detector,reward_hack_mitigationorecho_trap_enabled, refused when the trainer is built on trl's experimentalPPOTrainer, before the model loads (task: ppoitself still runs; the refusal is for the flags PPO cannot feed).- on a layer-streamed run, at trainer setup:
stream_expert_layout: per_experton a base that is notdeepseek_v3; a base checkpoint that is itself quantized (GPTQ, AWQ, bitsandbytes, compressed-tensors and the like, or an FP8 format other than DeepSeek-V3's block FP8), refused by name before the shard cache is written (#2103, #2061); a Kimi K2 config that the guard does not admit (#2107); and, understream_loss_chunk, a trainable output head or a model that changes its logits after the head. - on
backend: mlx, when the trainer starts: an SFT training split smaller thanbatch_size,eval_stepswith a validation split that comes out empty, DPO, ORPO or SimPO with fewer pairs thanbatch_sizeonce unusable rows are skipped, and KTO with fewer than 2 rows. - on
task: grpowithbackend: mlx, when the trainer starts (new in v0.77.1): a training split with fewer prompts than one optimizer update needs (batch_sizetimesgradient_accumulation_steps, divided bynum_generations), refused before the model loads; and a base that loads quantized in a way the trainer does not accept, refused right after the model loads (the rule changed in v0.77.2, below). The schema defaulttraining.quantization: 4bitloads on MLX, because there it only names a pre-quantized base. Through v0.77.1 every quantized base was refused here, so a config copied from an MLX SFT recipe with anmlx-community4-bit base passedsoup doctor --configandsoup train --dry-runand stopped after the load. (Since closed in v0.77.2, #2386 by @ybai08:task: grpoonbackend: mlxtrains on a base pre-quantized by mlx-lm at 4 bits inaffinemode, themlx-community/...-4bitrepositories andmlx_lm.convert -q, with the quantized layers frozen and only the LoRA adapter trained; any other quantized base is refused right after the load, naming the first layer outside the rule, andadapter_config.jsonrecordsbase_quantization. That covers 8-bit and mixed-bit bases,mxfp4,mxfp8,nvfp4, quantized Mixture-of-Experts layers and BitNet layers.training.quantization: 8bitstays refused at load, in reworded text:training.quantization='8bit' is not supported by task='grpo' on backend='mlx': MLX GRPO trains a dense base or one pre-quantized at 4 bits (affine), not an 8-bit one.Covered only by the hosted macOS MLX test job and not exercised by hand before the release; the site prints no MLX speed, memory or accuracy figure for it.)soup train --resumeand--hf-resumeexit 1 on this task at launch, even together with--dry-run, because the run saves only the adapter. See GRPO on MLX.
soup train --dry-run validates the config and the data and, for a run that is not layer-streamed and has a GPU whose memory it can read, the hardware-fit check; it does not run the layer-streaming VRAM pre-flight, which runs at trainer setup.
The 31 staged fields
These 31 fields are accepted by the schema, validated, and read by nothing. Since v0.77.0 each one set to a value other than the default in the second column stops the load with <field> is accepted but read by nothing; refused as of v0.77. Delete the line.; written at its default, a field loads. v0.76 warned about 29 of them. The two rl_checkpoint_include_* fields were never warned about: an explicit false loads and true is refused. None of the 31 changed what a run did, so deleting them changes no result. For regression gating and early stopping, use soup train --gate <suite.yaml>.
| Field | Default (loads) |
|---|---|
training.long_context_grpo | false |
training.vision_grpo | false |
training.quantize_ref_model | false |
training.grace_codebook | false |
training.grace_codebook_size | unset |
training.grace_codebook_dim | unset |
training.lr_groups | unset |
training.early_stop_patience | 2 |
training.citation_recall_threshold | unset |
training.forgetting_eval_steps | 100 |
training.forgetting_benchmark | mini_mmlu |
training.forgetting_stop | false |
training.checkpoint_eval_steps | 200 |
training.checkpoint_eval_metric | composite |
training.checkpoint_eval_tasks | unset |
training.checkpoint_keep_top | 3 |
training.convergence_window | 50 |
training.convergence_rel_tol | 0.005 |
training.rl_checkpoint_include_ref_model | false |
training.rl_checkpoint_include_rollout_buffer | false |
data.video_dir | unset |
data.video_fps | unset |
data.video_maxlen | unset |
data.image_min_pixels | unset |
data.image_max_pixels | unset |
data.image_resize_algorithm | unset |
data.split_thinking | false |
data.eval_on_each_dataset | false |
data.resize_vocab | false |
data.extend_conversation | false |
data.skip_prepare_dataset | false |
A soup sweep --param that sets one of them away from its default in any arm is refused the same way, before the first arm and before --dry-run prints the grid: sweep parameter sets a field that is accepted but read by nothing: training.early_stop_patience; refused as of v0.77. Remove it from --param., exit 1. A deprecated value such as data.remove_unused_columns=true is not pre-checked (--dry-run exits 0). The training-intelligence fields in this table (forgetting_*, checkpoint_eval_*, checkpoint_keep_top, convergence_*, early_stop_patience) are the tunables of features documented on Training intelligence and Training stability.
Deprecated values
Two config values and one command option that v0.76 loaded, ignored and warned about are refused since v0.77.0. The two config values were defaults that Soup's own tools wrote into the configs they generated, which is why they had one release of notice (#759, #795, #1418).
| Value | Since v0.77.0 | What to change |
|---|---|---|
data.remove_unused_columns: true | data.remove_unused_columns: true never had an effect (no trainer reads it; the trainers that set it pass false). Delete the line. Refused as of Soup v0.77. | Delete the line, or set it to false, the default |
An explicit training.quantization: 4bit or 8bit (or load_in_8bit: true) on distill, classifier, reranker, cross_encoder, prm, moe_lora_routing, unlearn or asr | training.quantization: 4bit has no effect on task='distill': its trainer never quantises the base, so no run can honour it. Delete the line or set quantization: none. Refused as of Soup v0.77. | Delete the line or set quantization: none. Unset resolves to none |
soup ab --beta | soup ab exits 2 before it reads a row: Error: --beta no longer does anything (#1418): ..., ending Remove --beta; to make accept_h0 stricter, lower --alpha. Refused as of Soup v0.77. | Remove --beta; lower --alpha for a stricter accept_h0 |
The first two are config values and stop the load. The third is a command option, so soup ab refuses it, not the loader.
AWQ and GPTQ export were removed in v0.77.0, which is a command change, not a config one: soup export --format awq or gptq exits 1 and names the formats that remain (gguf, onnx, tensorrt, bitnet, tq1_0, torchao, gguf-ud), soup quantize --to awq or gptq exits 2, and the [awq] and [gptq] extras no longer exist. AWQ and GPTQ export need v0.76.x and its [awq] or [gptq] extra, for example pip install "soup-cli[awq]<0.77"; upstream notes that both projects are archived and incompatible with [train]. Loading a base that is already AWQ- or GPTQ-quantized (training.quantization: awq or gptq) is unchanged. See Export.
Keys that are still unread and not refused
Not every key that nothing reads is in the staged table, and these load. House phrasing for them: accepted by the schema, but nothing in v0.77.2 reads it. Upstream names no release for refusing them.
- Four parent switches and one threshold:
training.forgetting_detection,training.checkpoint_intelligence,training.early_stop_on_regression,training.convergence_detection(whentrue) andtraining.forgetting_threshold(when it differs from the default).soup trainprints aNote:after the load that they are set but not enforced during training;soup doctor --configdoes not print it. Use--gate <suite.yaml>for a live eval gate, or runsoup evalorsoup diagnoseafter training. training.warmup_auto. It loads in silence.soup autopilotwrites it into the config it generates, and nothing that trains reads it.training.load_in_16bit,training.unsloth_bnb_4bitandtraining.llm_int8are aliases that the schema rewrites, not separate settings.
training.packing_cross_doc_attn_mask is not one of them: it is refused at load, as before.
Upstream tracks the class as #1814, and its v0.77.2 release notes list it as still open: its guard test lists the staged fields plus warmup_auto and forgetting_threshold among the declared fields that nothing consumes. Data pipeline pro covers the video and image fields.
What soup doctor --config does and does not check
soup doctor --config soup.yaml loads the file with the loader described above. So, on every task and backend, it reports unknown keys (all of them together; a config that has one stops there, before the staged fields are checked), then the staged fields and deprecated values (together, ahead of the rest), and the refusals on this page that happen at config load. It does not list every refusal in one run: it stops at the first cross-field refusal it hits, and a refusal of one data field can hide a cross-field one, so fix what it names and run it again until it prints no error. A refused config exits 2 and a config that loads exits 0. Since v0.77.0 it no longer prints All checks passed! above a refusal (#2106); the system, GPU and dependency tables still print first, and the config error follows them.
After a successful load it prints a Config check section: a table of settings known to be unread on a combination of task, backend and modality that upstream has reviewed. At v0.77.2 there are nine, with the counts as soup doctor --config printed them on the v0.77.2 binary for each combination: sft on backend: mlx (10 settings); dpo, orpo, simpo and kto on backend: mlx (5 each); grpo on backend: mlx (4 settings: use_galore, use_ring_attention, moe_lora and use_fsdp2_compile); a task: preference config on backend: mlx with preference_loss dpo, orpo or simpo prints its own task in the heading and the count of the native task it runs (5), so it is not a tenth combination (the v0.77.1 counts were 12 and 9: v0.77.2 dropped from the table the rows for training.use_lorafa and training.quantization_aware, which the loader already refused, and from the preference tables use_flash_attn and use_liger, which a preference task refuses too); sft on backend: unsloth (none, because its unread settings are refused at load instead); and sft on the transformers backend with a vision or an audio modality (data.mask_history, one each). A setting refused at load never reaches the table. For every other combination it prints None of the 0 setting(s) known to be unread on task=<task> backend=<backend> is switched on in this config. That line means "not reviewed", not an all-clear, and the reviewed combinations print the same form with their own count. Upstream tracks this as #1815.
soup plan and soup apply read the YAML under the read limits (a file over one exits 2, and since v0.77.2 so does a syntax error or a config that cannot be read, naming the config and the YAML location; through v0.77.1 a syntax error exited 1) and then run the loader's checks, so since v0.77.1 a staged field, a deprecated value, training.quantization_aware: true or any other schema error exits 1 with the lines soup train prints and writes no plan (at v0.77.0 and earlier they checked unknown keys only and wrote a plan). One config loads under soup train only because of a CLI flag: a distill config with training.minillm_enabled: true, training.minillm_teacher_mix_ratio: 0 and no training.minillm_on_policy loads under soup train --minillm-on-policy, because the flag sets the field before validation. soup plan and soup apply had no such flag through v0.77.1 and refused that config, so the YAML had to carry training.minillm_on_policy: true. (Since closed in v0.77.2: both take --minillm-on-policy, #2315 by @Nari-Ab, so the same distill config is validated and hashed like any other; soup apply keeps the flag in the soup train command it suggests and still only records the plan.) soup doctor --config is still the check to run first: it reports unknown keys together, then the staged fields, then the first other refusal it hits, so fix what it names and run it again until it prints no error. See Refused later than config load for what no load-time check can see, MLX honours its config for how the MLX table started, and Exit codes for the other commands' codes.
See also
- v0.77.2: the token rule and explicit refusals: the release page, with the four
task: sftrefusals, the MLX changes and the upgrade notes. - v0.77.1: data commands keep their input: the patch after it, with the plan and apply check and the unknown-key hints.
- v0.77.0: what v0.76 warned about is now refused: the release page, with the breaking changes and the re-run table.
- v0.76.0: settings that never took effect now stop the load: the release that refused the first set and gave the notice.
- v0.76.1: the bundled DPO examples train again: the patch that added the read limits.
- Configuration: the reference for the config file and how it is loaded.
- Pre-flight tooling and Fine-tune Doctor: the other checks to run before a long job.
- Exit codes.
Soup is free and Apache-2.0. If it saved you a training run, starring the repo costs nothing and helps most. You can also fund the GPU time behind the work a 4 GB laptop cannot reach.