TinyTorch/docs/tito/troubleshooting.md

Troubleshooting Guide

Common Issues & Solutions

Quick fixes for the most common TinyTorch problems

Purpose: Fast solutions to common issues. Get unstuck and back to building ML systems quickly.

---

Quick Diagnostic: Start Here

First step for ANY issue:

cd TinyTorch
source activate.sh
tito system health

This checks:

• ✅ Virtual environment activated
• ✅ Dependencies installed (NumPy, Jupyter, Rich)
• ✅ TinyTorch in development mode
• ✅ Data files intact
• ✅ All systems ready

If doctor shows errors: Follow the specific fixes below.

If doctor shows all green: Your environment is fine - issue is elsewhere.

---

Environment Issues

Problem: "tito: command not found"

Symptom:

$ tito module start 01
-bash: tito: command not found

Cause: Virtual environment not activated or TinyTorch not installed in development mode.

Solution:

# 1. Activate environment
cd TinyTorch
source activate.sh

# 2. Verify activation
which python  # Should show TinyTorch/venv/bin/python

# 3. Re-install TinyTorch in development mode
pip install -e .

# 4. Test
tito --help

Prevention: Always run source activate.sh before working.

Problem: "No module named 'tinytorch'"

Symptom:

>>> from tinytorch import Tensor
ModuleNotFoundError: No module named 'tinytorch'

Cause: TinyTorch not installed in development mode, or wrong Python interpreter.

Solution:

# 1. Verify you're in the right directory
pwd  # Should end with /TinyTorch

# 2. Activate environment
source activate.sh

# 3. Install in development mode
pip install -e .

# 4. Verify installation
pip show tinytorch
python -c "import tinytorch; print(tinytorch.__file__)"

Expected output:

/Users/YourName/TinyTorch/tinytorch/__init__.py

Problem: "Virtual environment issues after setup"

Symptom:

$ source activate.sh
# No (venv) prefix appears, or wrong Python version

Cause: Virtual environment not created properly or corrupted.

Solution:

# 1. Remove old virtual environment
rm -rf venv/

# 2. Re-run setup
./setup-environment.sh

# 3. Activate
source activate.sh

# 4. Verify
python --version  # Should be 3.8+
which pip  # Should show TinyTorch/venv/bin/pip

Expected: (venv) prefix appears in terminal prompt.

---

Module Issues

Problem: "Module export fails"

Symptom:

$ tito module complete 03
❌ Export failed: SyntaxError in source file

Causes:

1. Python syntax errors in your code
2. Missing required functions
3. NBGrader metadata issues

Solution:

Step 1: Check syntax:

# Test Python syntax directly (for developers)
python -m py_compile src/03_layers/03_layers.py

Step 2: Open in Jupyter and test:

tito module resume 03
# In Jupyter: Run all cells, check for errors

Step 3: Fix errors shown in output

Step 4: Re-export:

tito module complete 03

Common syntax errors:

• Missing : after function/class definitions
• Incorrect indentation (use 4 spaces, not tabs)
• Unclosed parentheses or brackets
• Missing return statements

Problem: "Tests fail during export"

Symptom:

$ tito module complete 05
Running tests...
❌ Test failed: test_backward_simple

Cause: Your implementation doesn't match expected behavior.

Solution:

Step 1: See test details:

# Tests are in the module file - look for cells marked "TEST"
tito module resume 05
# In Jupyter: Find test cells, run them individually

Step 2: Debug your implementation:

# Add print statements to see what's happening
def backward(self):
    print(f"Debug: self.grad = {self.grad}")
    # ... your implementation

Step 3: Compare with expected behavior:

• Read test assertions carefully
• Check edge cases (empty tensors, zero values)
• Verify shapes and types

Step 4: Fix and re-export:

tito module complete 05

Tip: Run tests interactively in Jupyter before exporting.

Problem: "Jupyter Lab won't start"

Symptom:

$ tito module start 01
# Jupyter Lab fails to launch or shows errors

Cause: Jupyter not installed or port already in use.

Solution:

Step 1: Verify Jupyter installation:

pip install jupyter jupyterlab jupytext

Step 2: Check for port conflicts:

# Kill any existing Jupyter instances
pkill -f jupyter

# Or try a different port
jupyter lab --port=8889 modules/01_tensor/

Step 3: Clear Jupyter cache:

jupyter lab clean

Step 4: Restart:

tito module start 01

Problem: "Changes in Jupyter don't save"

Symptom: Edit in Jupyter Lab, but changes don't persist.

Cause: File permissions or save issues.

Solution:

Step 1: Manual save:

In Jupyter Lab:
File → Save File (or Cmd/Ctrl + S)

Step 2: Check file permissions:

ls -la modules/01_tensor/01_tensor.ipynb
# Should be writable (not read-only)

Step 3: If read-only, fix permissions:

chmod u+w modules/01_tensor/01_tensor.ipynb

Step 4: Verify changes saved:

# Check the notebook was updated
ls -l modules/01_tensor/01_tensor.ipynb

---

Import Issues

Problem: "Cannot import from tinytorch after export"

Symptom:

>>> from tinytorch import Linear
ImportError: cannot import name 'Linear' from 'tinytorch'

Cause: Module not exported yet, or export didn't update __init__.py.

Solution:

Step 1: Verify module completed:

tito module status
# Check if module shows as ✅ completed

Step 2: Check exported file exists:

ls -la tinytorch/nn/layers.py
# File should exist and have recent timestamp

Step 3: Re-export:

tito module complete 03

Step 4: Test import:

python -c "from tinytorch.nn import Linear; print(Linear)"

Note: Use full import path initially, then check if from tinytorch import Linear works (requires __init__.py update).

Problem: "Circular import errors"

Symptom:

>>> from tinytorch import Tensor
ImportError: cannot import name 'Tensor' from partially initialized module 'tinytorch'

Cause: Circular dependency in your imports.

Solution:

Step 1: Check your import structure:

# In modules/XX_name/name_dev.py
# DON'T import from tinytorch in module development files
# DO import from dependencies only

Step 2: Use local imports if needed:

# Inside functions, not at module level
def some_function():
    from tinytorch.core import Tensor  # Local import
    ...

Step 3: Re-export:

tito module complete XX

---

Milestone Issues

Problem: "Milestone says prerequisites not met"

Symptom:

$ tito milestone run 04
❌ Prerequisites not met
   Missing modules: 08, 09

Cause: You haven't completed required modules yet.

Solution:

Step 1: Check requirements:

tito milestone info 04
# Shows which modules are required

Step 2: Complete required modules:

tito module status  # See what's completed
tito module start 08  # Complete missing modules
# ... implement and export
tito module complete 08

Step 3: Try milestone again:

tito milestone run 04

Tip: Milestones unlock progressively. Complete modules in order (01 → 20) for best experience.

Problem: "Milestone fails with import errors"

Symptom:

$ tito milestone run 03
Running: MLP Revival (1986)
ImportError: cannot import name 'ReLU' from 'tinytorch'

Cause: Required module not exported properly.

Solution:

Step 1: Check which import failed:

# Error message shows: 'ReLU' from 'tinytorch'
# This is from Module 02 (Activations)

Step 2: Re-export that module:

tito module complete 02

Step 3: Test import manually:

python -c "from tinytorch import ReLU; print(ReLU)"

Step 4: Run milestone again:

tito milestone run 03

Problem: "Milestone runs but shows errors"

Symptom:

$ tito milestone run 03
Running: MLP Revival (1986)
# Script runs but shows runtime errors or wrong output

Cause: Your implementation has bugs (not syntax errors, but logic errors).

Solution:

Step 1: Run milestone script manually:

python milestones/03_1986_mlp/03_mlp_mnist_train.py
# See full error output

Step 2: Debug the specific module:

# If error is in ReLU, for example
tito module resume 02
# Fix implementation in Jupyter

Step 3: Re-export:

tito module complete 02

Step 4: Test milestone again:

tito milestone run 03

Tip: Milestones test your implementations in realistic scenarios. They help find edge cases you might have missed.

---

Data & Progress Issues

Problem: ".tito folder deleted or corrupted"

Symptom:

$ tito module status
Error: .tito/progress.json not found

Cause: .tito/ folder deleted or progress file corrupted.

Solution:

Option 1: Let TinyTorch recreate it (fresh start):

tito system health
# Recreates .tito/ structure with empty progress

Option 2: Restore from backup (if you have one):

# Check for backups
ls -la .tito_backup_*/

# Restore from latest backup
cp -r .tito_backup_20251116_143000/ .tito/

Option 3: Manual recreation:

mkdir -p .tito/backups
echo '{"version":"1.0","completed_modules":[],"completion_dates":{}}' > .tito/progress.json
echo '{"version":"1.0","completed_milestones":[],"completion_dates":{}}' > .tito/milestones.json
echo '{"logo_theme":"standard"}' > .tito/config.json

Important: Your code in modules/ and tinytorch/ is safe. Only progress tracking is affected.

Problem: "Progress shows wrong modules completed"

Symptom:

$ tito module status
Shows modules as completed that you haven't done

Cause: Accidentally ran tito module complete XX without implementing, or manual .tito/progress.json edit.

Solution:

Option 1: Reset specific module:

tito module reset 05
# Clears completion for Module 05 only

Option 2: Reset all progress:

tito reset progress
# Clears all module completion

Option 3: Manually edit .tito/progress.json:

# Open in editor
nano .tito/progress.json

# Remove the module number from "completed_modules" array
# Remove the entry from "completion_dates" object

---

Dependency Issues

Problem: "NumPy import errors"

Symptom:

>>> import numpy as np
ImportError: No module named 'numpy'

Cause: Dependencies not installed in virtual environment.

Solution:

# Activate environment
source activate.sh

# Install dependencies
pip install numpy jupyter jupyterlab jupytext rich

# Verify
python -c "import numpy; print(numpy.__version__)"

Problem: "Rich formatting doesn't work"

Symptom: TITO output is plain text instead of colorful panels.

Cause: Rich library not installed or terminal doesn't support colors.

Solution:

Step 1: Install Rich:

pip install rich

Step 2: Use color-capable terminal:

• macOS: Terminal.app, iTerm2
• Linux: GNOME Terminal, Konsole
• Windows: Windows Terminal, PowerShell

Step 3: Test:

python -c "from rich import print; print('[bold green]Test[/bold green]')"

---

Performance Issues

Problem: "Jupyter Lab is slow"

Solutions:

1. Close unused notebooks:

In Jupyter Lab:
Right-click notebook tab → Close
File → Shut Down All Kernels

2. Clear output cells:

In Jupyter Lab:
Edit → Clear All Outputs

3. Restart kernel:

Kernel → Restart Kernel

4. Increase memory (if working with large datasets):

# Check memory usage
top
# Close other applications if needed

Problem: "Export takes a long time"

Cause: Tests running on large data or complex operations.

Solution:

This is normal for:

• Modules with extensive tests
• Operations involving training loops
• Large tensor operations

If export hangs:

# Cancel with Ctrl+C
# Check for infinite loops in your code
# Simplify tests temporarily, then re-export

---

Platform-Specific Issues

macOS: "Permission denied"

Symptom:

$ ./setup-environment.sh
Permission denied

Solution:

chmod +x setup-environment.sh activate.sh
./setup-environment.sh

Windows: "activate.sh not working"

Solution: Use Windows-specific activation:

# PowerShell
.\venv\Scripts\Activate.ps1

# Command Prompt
.\venv\Scripts\activate.bat

# Git Bash
source venv/Scripts/activate

Linux: "Python version issues"

Solution: Specify Python 3.8+ explicitly:

python3.8 -m venv venv
source activate.sh
python --version  # Verify

---

Getting More Help

Debug Mode

Run commands with verbose output:

# Most TITO commands support --verbose
tito module complete 03 --verbose

# See detailed error traces
python -m pdb milestones/03_1986_mlp/03_mlp_mnist_train.py

Check Logs

Jupyter Lab logs:

# Check Jupyter output in terminal where you ran tito module start
# Look for error messages, warnings

Python traceback:

# Full error context
python -c "from tinytorch import Tensor" 2>&1 | less

Community Support

GitHub Issues: Report bugs or ask questions

• Repository: mlsysbook/TinyTorch
• Search existing issues first
• Include error messages and OS details

Documentation: Check other guides

• Module Workflow
• Milestone System
• Progress & Data

---

Prevention: Best Practices

Avoid issues before they happen:

1. Always activate environment first:

   source activate.sh
   

2. Run tito system health regularly:

   tito system health
   

3. Test in Jupyter before exporting:

   # Run all cells, verify output
   # THEN run tito module complete
   

4. Keep backups (automatic):

   # Backups happen automatically
   # Don't delete .tito/backups/ unless needed
   

5. Use git for your code:

   git commit -m "Working Module 05 implementation"
   

6. Read error messages carefully:

   • They usually tell you exactly what's wrong
   • Pay attention to file paths and line numbers

---

Quick Reference: Fixing Common Errors

Error Message	Quick Fix
tito: command not found	source activate.sh
ModuleNotFoundError: tinytorch	pip install -e .
SyntaxError in export	Fix Python syntax, test in Jupyter first
ImportError in milestone	Re-export required modules
.tito/progress.json not found	tito system health to recreate
Jupyter Lab won't start	pkill -f jupyter && tito module start XX
Permission denied	chmod +x setup-environment.sh activate.sh
Tests fail during export	Debug in Jupyter, check test assertions
Prerequisites not met	tito milestone info XX to see requirements

---

Still Stuck?

Need More Help?

Try these resources for additional support

Report Issue → Command Reference →

---

Most issues have simple fixes. Start with tito system health, read error messages carefully, and remember: your code is always safe in modules/ - only progress tracking can be reset.