Unit 0 troubleshooting
← Unit 0 — First Tiny-LM Run · Diagnostic & learning path → · Glossary
Run the diagnostic first and fix the first failing check:
python examples/diagnose_unit0.py| Symptom | Meaning | Recovery |
|---|---|---|
python: command not found |
usually: the course environment is not active in this terminal | Activate .venv first (every session); if that fails, try python3, and install Python 3.11+ if both fail |
No module named llm_course |
environment is inactive or package was not installed | Activate .venv, then run python -m pip install -e ".[dev,docs]" |
| install appears slow | PyTorch is a large dependency | Keep the terminal open; wait for the final success/error line |
| requested MPS/CUDA is unavailable | accelerator is unsupported or not visible to PyTorch | rerun with --device cpu; this is the full required route |
permission error under artifacts/ |
current directory is not writable | use --artifact-dir with a writable project-local directory |
| checkpoint format/vocabulary error | assets came from another course version | run with a fresh directory such as --artifact-dir artifacts/unit0-clean |
--prompt must contain at least one character |
a language model needs at least one context token | provide a non-empty --prompt |
prompt contains ? unexpectedly |
unsupported characters map to the unknown token | use only a–z, space, and ! , - . ?; capitals are read as lowercase (the alphabet is in Unit 0 under “Your own change”, after the fixed example) |
| sampled runs differ | seed or command differs | use the same --seed, prompt, target, boost, and course commit |
Backend isolation
Check the mandatory CPU route independently:
python examples/diagnose_unit0.py --device cpu
python examples/run_unit0.py --device cpuIf CPU passes but MPS/CUDA fails, record backend, PyTorch version, command, and full error. Continue the lesson on CPU; acceleration is optional.
Evidence for a useful bug report
Include:
- operating system and Python version;
- output of
python examples/check_hardware.py --skip-benchmark; - output of
python examples/diagnose_unit0.py; - exact command and first complete traceback;
- whether
--device cpusucceeds.
Never attach generated checkpoints, company data, credentials, or personal information.
← Unit 0 — First Tiny-LM Run · Diagnostic & learning path → · Glossary