Skip to content

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.

bash
soup doctor --config soup.yaml

Run 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:

  1. 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.yaml may 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 example Config 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: ... and Config file soup.yaml is a directory, not a file. soup train exits 1 and soup doctor --config exits 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.
  2. The file must be a YAML mapping. An empty file prints Config file is empty and a list or a bare value prints Config must be a YAML mapping, got list; soup train exits 1 on both and soup doctor --config exits 2.
  3. 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 as learning_rate, num_train_epochs, and per_device_train_batch_size (at the top level and under training:), grad_accum_steps and gradient_accumulation (under training: only), lr, epochs and batch_size written 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 gets unknown 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 names training.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, so training.learning_rate read - refused. with no hint. Typos such as early_stopp_patience land here, and they are checked before anything else: nothing else is reported until the unknown keys are gone.
  4. 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 reads training -> optimizer: <message>; a refusal that spans several fields prints its message alone, or after training: or data: when it comes from that section's own check. Since v0.77.0 the terminal no longer prints Pydantic's Value error, prefix in front of a message; the loader that the API and the Web UI use (load_config_from_string) raises a ValueError whose text keeps it.
  5. 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 example training.grace_codebook: true without a size and a dimension, or data.video_fps on 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).

Outcomesoup doctor --configsoup 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 2prints Config validation error: (or the read-limit line) and exits 1, before it imports the training stack
Loadsexits 0trains

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):

yaml
base: org/model
task: sft
data:
  train: ./data.jsonl
training:
  early_stop_patience: 3
  lr_groups:
    - pattern: ".*lora_A.*"
      lr: 0.001
text
Config 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

SettingRefused whenMessage beginsWhat to change
training.ebft_variant, training.ebft_temperatureebft_variant has any value (#1230); ebft_temperature alone is refused tootraining.ebft_variant is refused (#1230): EBFT is not yet a distinct objective.Remove both keys
training.gdpo_variantany 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_awaretrue (#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_longloratrue (#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_typelongrope (#1239)training.rope_scaling_type='longrope' is refused (#1239): it cannot extend any checkpoint.Choose another rope_scaling_type
training.kernel_auto_composetrue (#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.quantizationbitnet_1.58 (#825, #981)BitNet 1.58 training is not implemented yet;Export an existing BitNet checkpoint instead
training.tts_family with data.format: audiospark 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_modtrue 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: unslothtraining.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_csmwith 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 trainerSesame CSM requires training.quantization='none' / Sesame CSM does not support training.tts_emotionUse 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

SettingRefused whenMessage beginsWhat to change
training.rope_scaling_typetask 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 messagetraining.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_layersset 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_layersdiffers from expand_layers (#1409)freeze_trainable_layers: 32 does not match expand_layers: 4.Set both to the same number
training.expand_layersset 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_layersquantization 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_layersthe 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_layerswith 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

SettingRefused whenMessage beginsWhat to change
training.loraplus_lr_ratiocombined 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_ratiocombined with use_galore: true (#1210)training.loraplus_lr_ratio and training.use_galore are mutually exclusive:Enable one
training.loraplus_lr_ratiobackend: mlx (#1324)Refused: training.loraplus_lr_ratio is not implemented on backend='mlx'Remove it, or use backend: transformers
training.loraplus_lr_rationo 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_lorafacombined with loraplus_lr_ratio (#725)training.use_lorafa and training.loraplus_lr_ratio are mutually exclusive:Enable one
training.use_lorafatask 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_lorafaoptimizer: 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_strategya 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_doraon 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_strategya 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_doraquantization 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_strategypissa 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_patternbackend: mlx (#1996) or backend: unsloth (#2153), new in v0.77.0 (both backends ignored the pattern before). An empty {} loadstraining.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.loratask: 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.r0 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_stepsquantization 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_stepswith lora.use_dora: true, use_fsdp2_compile: true or stream_layers: true (#693), or on backend: mlxrelora_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_stepsthe 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 bcotraining.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 weightsRemove relora_steps (or the term from preference_loss_weights); sft, orpo, simpo and grpo with grpo_beta: 0 keep ReLoRA
training.moe_loratask: 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_coeffa 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).

SettingRefused whenMessage beginsWhat to change
training.optimizeradam_mini, adamw_apex_fused, ao_adamw_4bit, ao_adamw_8bit, ao_adamw_fp8, badam, came_pytorch or dionoptimizer='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.optimizermuon or adamw_hf on any backend except mlxtraining.optimizer='muon' only works on backend: mlx (the MLX backend builds it itself);Switch to backend: mlx, or use a supported optimizer

Quantization

SettingRefused whenMessage beginsWhat 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.quantizationgptq, 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.quantization8bit 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_storagequantization 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_storageset 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: fp8backend: 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

SettingRefused whenMessage beginsWhat to change
backend: unslothtask 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: unslothtask: dpo with modality: vision (#1393)task='dpo' with modality='vision' requires backend='transformers':Use backend: transformers
backend: unslothtask: 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: mlxa 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 defaulttraining.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 tasksdpo, 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 audiotask: distill (new in v0.77.0, #2014)task='distill' requires modality='text': the distill trainer loads a text-only student and teacherUse modality: text
basea 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_attntask 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_precisiontask 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 GPURemove it, or set precision explicitly
training.reward_fn: judge_ranka 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: truelora.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_ratiotask 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_alphaany 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_eota 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_faithfula 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_sizetask: 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_sizetask: 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 1Raise batch_size, or choose another embedding loss
training.dpo_ref_regen_epochslora.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_ratiominillm_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_sizeoutside 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_betaa boolean (#1247)grpo_beta must not be a booleanGive a number; 0 runs KL-free
training.loss_watchdog, training.loss_spike_recovery, training.grad_accum_auto_tunetrue 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 SFTRemove it for that task or backend
training.eval_stepsnot an integer (#1223)training.eval_steps must be an int, not a boolGive an integer number of optimizer steps
training.eval_stepsdata.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_stepstask 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

SettingRefused whenMessage beginsWhat to change
data.add_new_tokens, data.new_special_tokenstask 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_tokenswith data.format: pre_tokenizedformat='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_tokenizedwith modality: visiondata.format='pre_tokenized' cannot be combined with modality='vision';Train from the source format
data.chat_templatetask 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 taskRemove it
data.chat_templatebackend: 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_historytrue with train_on_responses_only: false (#761)data.mask_history requires data.train_on_responses_only: trueSet train_on_responses_only: true, or drop mask_history
data.format: llava, sharegpt4von 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.

SettingRefused whenMessage beginsWhat 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_chunkset away from its default while stream_layers is falsetraining.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_aheadstream_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_aheadabove 8 (#971)training -> stream_read_ahead: Input should be less than or equal to 8Use 8 or less
training.batch_size: autowith 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_cetrue 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_awareunder 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_coeffa 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_chunka 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_recomputeoff 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_layoutper_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_cachewithout quantization: 4bit and double quantization (new in v0.77.0, #1892)training.stream_nf4_scale_cache needs quantization='4bit' with double quantizationSet 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):

PathRefused when set
modality: vision or modality: audioreasoning_effort, train_on_eot, use_flash_attn, use_liger
backend: mlxreasoning_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: unslothuse_flash_attn, use_liger
data.format: raftreasoning_effort, train_on_eot
data.format: pre_tokenizedreasoning_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:

text
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_tokens or lm_head of 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_layers or freeze_ratio under LoRA with a target peft cannot restrict by layer: a string lora.target_modules (a regular expression, all-linear, or what auto resolves 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_weights blend with a dpo or ipo term under a simpo or orpo primary, together with lora.init_strategy pissa, olora or loftq, refused at trainer setup before the model loads (#1828). The same blend with relora_steps is refused at config load instead (#1891, the relora_steps row above). A bco term in a blend is still refused at trainer setup.
  • task: ppo with reward_hack_detector, reward_hack_mitigation or echo_trap_enabled, refused when the trainer is built on trl's experimental PPOTrainer, before the model loads (task: ppo itself still runs; the refusal is for the flags PPO cannot feed).
  • on a layer-streamed run, at trainer setup: stream_expert_layout: per_expert on a base that is not deepseek_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, under stream_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 than batch_size, eval_steps with a validation split that comes out empty, DPO, ORPO or SimPO with fewer pairs than batch_size once unusable rows are skipped, and KTO with fewer than 2 rows.
  • on task: grpo with backend: mlx, when the trainer starts (new in v0.77.1): a training split with fewer prompts than one optimizer update needs (batch_size times gradient_accumulation_steps, divided by num_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 default training.quantization: 4bit loads 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 an mlx-community 4-bit base passed soup doctor --config and soup train --dry-run and stopped after the load. (Since closed in v0.77.2, #2386 by @ybai08: task: grpo on backend: mlx trains on a base pre-quantized by mlx-lm at 4 bits in affine mode, the mlx-community/...-4bit repositories and mlx_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, and adapter_config.json records base_quantization. That covers 8-bit and mixed-bit bases, mxfp4, mxfp8, nvfp4, quantized Mixture-of-Experts layers and BitNet layers. training.quantization: 8bit stays 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 --resume and --hf-resume exit 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>.

FieldDefault (loads)
training.long_context_grpofalse
training.vision_grpofalse
training.quantize_ref_modelfalse
training.grace_codebookfalse
training.grace_codebook_sizeunset
training.grace_codebook_dimunset
training.lr_groupsunset
training.early_stop_patience2
training.citation_recall_thresholdunset
training.forgetting_eval_steps100
training.forgetting_benchmarkmini_mmlu
training.forgetting_stopfalse
training.checkpoint_eval_steps200
training.checkpoint_eval_metriccomposite
training.checkpoint_eval_tasksunset
training.checkpoint_keep_top3
training.convergence_window50
training.convergence_rel_tol0.005
training.rl_checkpoint_include_ref_modelfalse
training.rl_checkpoint_include_rollout_bufferfalse
data.video_dirunset
data.video_fpsunset
data.video_maxlenunset
data.image_min_pixelsunset
data.image_max_pixelsunset
data.image_resize_algorithmunset
data.split_thinkingfalse
data.eval_on_each_datasetfalse
data.resize_vocabfalse
data.extend_conversationfalse
data.skip_prepare_datasetfalse

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).

ValueSince v0.77.0What to change
data.remove_unused_columns: truedata.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 asrtraining.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 --betasoup 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 (when true) and training.forgetting_threshold (when it differs from the default). soup train prints a Note: after the load that they are set but not enforced during training; soup doctor --config does not print it. Use --gate <suite.yaml> for a live eval gate, or run soup eval or soup diagnose after training.
  • training.warmup_auto. It loads in silence. soup autopilot writes it into the config it generates, and nothing that trains reads it.
  • training.load_in_16bit, training.unsloth_bnb_4bit and training.llm_int8 are 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

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.