Troubleshooting

Start every diagnosis the same way, from your TinyTorch folder:

source .venv/bin/activate     # Windows (Git Bash): source .venv/Scripts/activate
tito system health

tito system health checks Python, the virtual environment, the required packages, the Jupyter kernel, and the project folders, and marks whatever is missing; it exits with status 1 when it finds an issue. If everything is green, the problem is in your code rather than your setup, and the module page’s When it fails section is the place to look.

Figure 1: The TinyTorch 4-stage diagnostic triage tree. Diagnose errors by layer: shell environment activation, environment dependencies and Jupyter kernel, exercise unit tests, or cross-module integration and exported code.

Setup

tito: command not found
The virtual environment is not active, so its tito is not on your path. Run source .venv/bin/activate (on Windows, source .venv/Scripts/activate in Git Bash) from the TinyTorch folder. If it is still missing, reinstall the package into the environment with python -m pip install -e ..
ModuleNotFoundError: No module named 'tinytorch'
Python is running outside the virtual environment. In a terminal, activate it as above. In a notebook, the kernel is the usual cause: open notebooks with tito module start or tito module resume, which launch Jupyter from the environment, and tito system health reports whether the kernel is set up.
No TinyTorch modules found
tito was run outside your TinyTorch folder, so it cannot find src/ and modules/. Run cd tinytorch (the folder the installer created) and try again.
The environment is broken beyond repair
Rebuild it. tito lives inside .venv, so recreate the environment with Python first: 
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pip install -e .
tito setup
This touches neither your notebooks in modules/ nor your progress in .tito/.
Windows
Use Git Bash, which comes with Git for Windows, for the installer and for every tito command. The environment’s activation script is .venv/Scripts/activate rather than .venv/bin/activate.

Completing a module

❌ Unit tests failed for 03_layers
A test inside your notebook failed, and nothing was exported or recorded. The traceback above this line names the test and the message; the module page’s When it fails section explains the common ones. Fix the notebook and run tito module complete again.
💡 Fix the syntax error in your notebook and try again
A cell does not parse, so nothing can be exported. The line above names the problem. Run the notebook top to bottom in Jupyter to find the cell.
❌ Integration tests failed for 03_layers
Your notebook’s own tests passed, but the exported package failed a test that imports it together with earlier modules. The usual cause is a function that works on the small inputs in the notebook but not on other shapes or on inputs produced by earlier modules. The output names the failing test and file; rerun tito module complete after the fix, since it re-exports before testing again.
⚠️ You must complete module 04 first
Modules are completed in order. Run tito module status to see which one is missing, and complete it first.

Jupyter

Jupyter Lab is already running
tito reuses the server it started earlier instead of opening a second one. Open the address it prints, usually http://localhost:8888, and select the notebook there.
My notebook is gone
tito module resume notices a missing notebook for a module you had started and recreates it from the source. The recreated notebook is a fresh copy, so work that was only in the deleted file is lost.

Milestones

Prerequisites Not Met
The milestone needs modules you have not completed. The panel lists the tito module complete commands to run. tito milestone info NN shows the full list.
A milestone fails with an import or attribute error after you changed a module
Milestones import the exported tinytorch package, not your notebook. Edits reach the package only when you run tito module complete again for that module.

Still stuck

Search or open an issue on GitHub, with the command you ran, the full error, your operating system, and the output of tito system info.

Back to top