Debugging Silent Training Failures

Debugging Silent Training Failures

Overview

The defining property of a broken neural net is that nothing breaks. There is no stack trace, no exception, no warning. You get a loss curve and a number, and both look plausible.

Core principle: Do not guess at hyperparameters. Read the symptom off the curve, form one hypothesis, and test it with the cheapest check that would disprove it.

Prerequisite mindset: Most "training problems" are pipeline bugs. Before adjusting a learning rate, ask whether the model has ever proven it can overfit a single batch. If it hasn't, that is the bug.

The Iron Law

THREE FAILED HYPERPARAMETER CHANGES MEANS IT IS A BUG, NOT A HYPERPARAMETER.

Stop tuning. Go back to ml-superpowers:building-the-training-skeleton and run every sanity check.

First Response, Always

Before consulting any table below, run these three. They resolve most cases in under five minutes:

1. Overfit a single batch of 2-10 examples. Can't reach near-zero loss? The

bug is in your gradient path, loss, or targets. Nothing else matters yet.

1. Print the exact tensor entering the model, immediately before the forward

pass. Decode it back to text or render it to an image.

1. Check loss at step 0 against -log(1/n_classes).

Symptom Table

Loss behaviour

| Symptom | Likely causes | Cheapest check | |---|---|---| | Loss is NaN/Inf | LR too high; division by zero in a custom loss; fp16 overflow; log of zero; bad input values | Print loss per step to find the first NaN; check inputs for NaN; drop LR 10x | | Loss starts far above expected | Wrong class count; bad init; logits scaled wrong; double softmax | Compute -log(1/n) and compare exactly | | Loss starts far below expected | Label leakage — the answer is in the input | Zero the input; loss should jump to the theoretical value | | Loss flat from step 0 | LR too low; frozen params; missing loss.backward() or optimizer.step(); detached graph; wrong param group in optimizer | Print grad norms; assert requires_grad on the params you expect | | Loss drops fast then plateaus high | Model only learned the class prior; capacity bottleneck; LR decayed to zero | Compare to input-independent baseline; print current LR | | Loss oscillates wildly | LR too high; batch too small; bad normalization | Drop LR 10x; increase batch | | Loss decreases then suddenly spikes | LR warmup ended badly; exploding gradient; a corrupt example | Add gradient clipping; log which batch preceded the spike | | Loss decreases but predictions never change | Loss computed on the wrong tensor; mask zeroing everything | Print predictions on a fixed batch each epoch |

Metric behaviour

| Symptom | Likely causes | Cheapest check | |---|---|---| | Accuracy suspiciously high | Train/test leakage; duplicates across splits; label in the features; eval on training data | Hash and intersect splits; check per-class breakdown | | Better than the human baseline | Almost always leakage or a broken metric | Grade 20 predictions by hand | | Accuracy equals the majority class rate | Model learned the prior only; input not reaching the model | Input-independent baseline comparison | | Val loss much lower than train loss | Augmentation/dropout active at eval-time comparison; val split is easier; train loss includes a regularization term | Compare like for like: eval mode, same augmentation, loss only | | Metric doesn't reproduce across runs | Seed unfixed; non-deterministic ops; eval on a random subset | Fix the seed; evaluate the full set | | Great in eval, bad in production | Distribution shift; preprocessing differs between paths | Run the production preprocessing on the eval set |

Curve shapes

| Symptom | Diagnosis | Action | |---|---|---| | Train ↓, Val ↓ then ↑ | Classic overfitting | Early stopping — ml-superpowers:regularizing-a-model | | Train high, Val high | Underfitting or a bug | Overfit one batch. Can't? It's a bug. | | Train ↓↓, Val flat | Memorizing without generalizing | More/better data, augmentation | | Both flat at chance | Input carries no signal, or is not connected | Input-independent baseline | | Train loss < 0 | Wrong reduction or a sign error | Read the loss function line by line |

Modern Failure Modes

Fine-tuning and LLM pipelines have their own silent bugs, all of which train cleanly:

| Symptom | Likely cause | |---|---| | Fine-tune produces base-model-quality output | Adapter not merged/loaded at inference; LR far too low; loss mask covering nothing | | Model repeats the prompt back | Loss applied to prompt tokens as well as completion | | Answers truncated mid-sentence | max_len cutting training examples; EOS token never learned | | Output has stray template markers | Chat template mismatch between training and inference | | Loss much higher than base model at step 0 | Tokenizer or template differs from pretraining | | Eval scores cluster at one value | Rubric not discriminative; judge ignoring the criteria | | RAG answers ignore retrieved context | Context past the effective attention window; retrieval returning nothing relevant |

The Investigation Loop

1. State one hypothesis — "I think X because Y." Write it down.
2. Pick the cheapest disproving check — usually a print statement, not a run.
3. Change one thing. Never two.
4. Verify the prediction. Wrong? New hypothesis. Do not stack fixes.
5. After 3 failed hypotheses, stop and re-run the full stage 2 checklist.

For non-ML bugs found along the way, use superpowers:systematic-debugging.

Common Rationalizations

| Excuse | Reality | |---|---| | "Let me try a lower learning rate" | If you don't know why, this is guessing. Overfit one batch first. | | "It's probably just needs more epochs" | Flat at chance for 10 epochs will be flat at chance for 100. | | "The pipeline is from a working repo" | Working for their data and shapes. Run the checks on yours. | | "94% is good enough, ship it" | 94% against what baseline? Suspicious numbers are usually leakage. | | "I'll change LR and batch size together to save time" | Then you learn nothing from the result. One at a time. | | "NaN happens sometimes, I'll restart" | NaN is deterministic given a seed. Find the first one. |

Red Flags

• Adjusting hyperparameters without a stated hypothesis
• More than three consecutive changes with no explanation of any of them
• Never having printed a real input tensor
• Accepting a good number without checking for leakage
• "It works now" with no explanation of what was wrong

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Umaraslam66
• Source: Umaraslam66/ml-superpowers
• License: MIT

Install and usage instructions live in the source repository linked above.