cs249r_book/tinytorch/site/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 .venv/bin/activate
tito system health

This checks:

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

If health shows errors: Follow the specific fixes below.

If health 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 .venv/bin/activate

# 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 .venv/bin/activate 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 .venv/bin/activate

# 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 .venv/bin/activate
# 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
tito setup

# 3. Activate
source .venv/bin/activate

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

Expected: (venv) prefix appears in terminal prompt.

System Updates

Problem: "How do I update TinyTorch?"

Check for updates:

tito system update --check

Install updates:

tito system update

What gets updated:

• ✅ TinyTorch framework code (tinytorch/ package)
• ✅ TITO CLI commands and tools
• ✅ Bug fixes and improvements
• ✅ New features

What stays safe:

• ✅ Your module implementations (modules/ folder)
• ✅ Your progress tracking (.tito/ folder)
• ✅ Your exported code
• ✅ All your work is preserved

The update process:

1. Checks current version
2. Queries GitHub for latest release
3. Shows what will be updated
4. Asks for confirmation
5. Downloads and installs update
6. Preserves all your work

Manual update (if needed):

curl -fsSL mlsysbook.ai/tinytorch/install.sh | bash

Problem: "Will updating delete my code?"

Answer: No! Your code is completely safe.

What's protected during updates:

• Your implementations in modules/XX_name/ notebooks
• Your progress data in .tito/
• Your completion history
• Any custom modifications you've made

How updates work:

1. Only the TinyTorch framework code gets updated
2. The installer script preserves your modules/ directory
3. Your .tito/ progress folder stays intact
4. Student work is never touched

Best practice:

# Before updating, verify your work is saved
tito module status  # Check completion status
git status          # If using version control

# Then update safely
tito system update

If something goes wrong:

• Your code is in modules/ - always safe
• Framework is in tinytorch/ - gets replaced
• Re-export your modules if needed: tito module complete XX

Problem: "Update failed or interrupted"

Symptom: Update command failed or was interrupted

Solution:

Step 1: Check environment:

source .venv/bin/activate
tito system health

Step 2: Try manual install:

curl -fsSL mlsysbook.ai/tinytorch/install.sh | bash

Step 3: Verify installation:

tito --version
tito system health

Step 4: Re-export modules if needed:

# If imports fail, re-export your completed modules
tito module complete 01
tito module complete 02
# ... etc for each completed module

Common causes:

• Network interruption during download
• Permission issues
• Conflicting Python packages

Prevention: Ensure stable internet and proper permissions before updating

Problem: "After update, imports are broken"

Symptom:

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

Cause: Update replaced framework files, need to re-export completed modules

Solution:

Step 1: Check what you've completed:

tito module status

Step 2: Re-export completed modules:

# For each module showing as completed
tito module complete 01
tito module complete 02
# etc...

Step 3: Test imports:

python -c "from tinytorch import Tensor; print('Success!')"

Why this happens:

• Updates may change internal framework structure
• Your implementations in modules/ are safe
• Just need to re-export to tinytorch/ package

Quick fix for all modules:

# Check your progress
cat .tito/progress.json

# Re-export each completed module
for i in 01 02 03 04 05; do
    tito module complete $i
done

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: Delete progress file:

# Remove progress tracking (will be recreated)
rm .tito/progress.json
tito system health # Recreates the file

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 .venv/bin/activate

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

$ tito setup
Permission denied

Solution:

pip install -e .
tito setup

Windows: Using TinyTorch

TinyTorch works on Windows via Git Bash (included with Git for Windows).

Install Git for Windows (if needed):

• Download from git-scm.com/download/win
• Run installer with default options

Use Git Bash for all TinyTorch commands:

# Open Git Bash from Start Menu
# Navigate to your project folder
cd ~/projects

# Install TinyTorch
curl -sSL mlsysbook.ai/tinytorch/install.sh | bash

# Activate (note the Scripts path on Windows)
cd tinytorch
source .venv/Scripts/activate

# Run TinyTorch
tito setup

Why Git Bash? TinyTorch uses bash scripts that work consistently across macOS, Linux, and Windows via Git Bash.

Windows: Virtual Environment Activation

Solution: Use the correct activation path for your shell on Windows:

# Git Bash (recommended)
source .venv/Scripts/activate

# Note: The path is Scripts/ not bin/ on Windows

If using PowerShell or CMD (not recommended):

# PowerShell
.\.venv\Scripts\Activate.ps1

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

Linux: "Python version issues"

Solution: Specify Python 3.8+ explicitly:

python3.8 -m venv venv
source .venv/bin/activate
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: harvard-edge/cs249r_book
• 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 .venv/bin/activate

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 .venv/bin/activate
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	pip install -e . then tito setup
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.