Jupyter Notebook Troubleshooting Guide

This folder contains two Jupyter notebooks designed to help students learn by debugging intentional errors commonly encountered in data science and machine learning workflows.

---

Learning Outcomes

By completing these notebooks, students will:

• Understand how Jupyter kernel state and cell execution order work
• Debug common file path and module import errors
• Handle data type mismatches and missing values
• Recognize and fix shape incompatibilities in NumPy and scikit-learn
• Prevent variable overwriting and namespace issues
• Learn when kernel restart is necessary
• Practice systematic debugging strategies

---

Repository Structure

jupyter-error-lab/
│
├── 01_notebook_errors.ipynb       # Jupyter & environment fundamentals
├── 02_data_and_ml_errors.ipynb    # Data science & ML pipeline errors
│
├── data/
│   ├── sample_data.csv            # Lowercase filename
│   ├── Sample_Data.csv            # Uppercase (for case-sensitivity demo)
│   └── wrong_format.txt           # Non-CSV file for format error demo
│
├── fake_modules/
│   └── pandas.py                  # Fake module for shadowing demonstration
│
└── README.md                      # This file

---

How to Use in the Classroom

For Instructors

1. Setup: Share this repository with students via Git clone, download, or LMS upload.

2. Instruct students to:

   • Open 01_notebook_errors.ipynb first
   • Run cells top to bottom one at a time
   • Observe each error carefully
   • Read the explanation in markdown cells
   • Apply the suggested fix

3. Classroom Flow:

   • Self-paced: Students work individually, asking for help when stuck
   • Guided walkthrough: Project notebook and discuss each error as a class
   • Pair programming: Students debug together in pairs

4. Assessment Options:

   • Ask students to fix all errors and submit corrected notebooks
   • Quiz on error types and their fixes
   • Have students write their own error examples

For Students

IMPORTANT INSTRUCTIONS

• DO NOT skip cells or run out of order
• DO NOT fix all errors immediately—learn from each one first
• DO restart kernel (Kernel → Restart) when instructed
• DO read error messages carefully before looking at explanations

BEFORE YOU START:

• Each notebook includes "Concept" sections explaining theoretical background
• Read the "Key Concepts You'll Learn" section at the top of each notebook
• Pay attention to conceptual explanations—they help you understand WHY errors occur
• Understanding theory helps you debug faster in real projects!

Workflow:

1. Open 01_notebook_errors.ipynb
2. Read the "Key Concepts You'll Learn" section at the top
3. Run first code cell
4. When you see an error:
   • Read the error message carefully
   • Check the "Concept" explanation above the error (if present)
   • Try to understand what went wrong
   • Read the markdown explanation below
   • Apply the fix (uncomment correct version or edit cell)
5. Repeat for each error scenario
6. Move to 02_data_and_ml_errors.ipynb when done

---

Technical Requirements

Dependencies

Install required packages:

pip install jupyter numpy pandas matplotlib scikit-learn tqdm

Python Version

• Python 3.10.11 (recommended and tested)

Files Included

• Notebooks: Two error-filled notebooks with embedded conceptual explanations
• Data files: Sample CSV and text files for demonstrations
• Supporting files: Fake modules for import shadowing examples

---

Error Coverage

Notebook 1: Jupyter & Environment Errors (16 errors)

1. IndentationError / SyntaxError (with indentation concept explanation)
2. Cell Not Executed → NameError
3. Kernel Restart Clearing Variables (with kernel concept explanation)
4. Import Works Once, Fails Later (with import caching explanation)
5. Relative Path Changes After os.chdir (with path concepts)
6. Multiple Notebooks Same Kernel Confusion
7. FileNotFoundError - Wrong Relative Path
8. Case-Sensitive Filename Issue
9. File Exists Locally But Not in Notebook Directory
10. Reading Wrong File Format
11. ModuleNotFoundError
12. Shadowed Module Name
13. Restart Required After Install
14. No Output Displayed - Missing Print
15. Output Truncation for Large DataFrame
16. Plot Not Displaying

Notebook 2: Data & ML Errors (17 errors)

1. Variable Overwriting
2. Function Defined But Not Called
3. Shape Mismatch in NumPy/Sklearn (with array shape concepts)
4. Pandas KeyError - Missing Column (with DataFrame column concepts)
5. IndexError (Out-of-Bounds Access)
6. NaNs Causing Model Failure (with missing value concepts)
7. Wrong Data Types in DataFrame (with dtype concepts)
8. Silent Dtype Upcasting (with type coercion explanation)
9. Train-Test Column Mismatch
10. Train-Test Leakage (comprehensive data leakage explanation)
11. Randomness / Non-Reproducibility (with random seed concepts)
12. Long-Running Cell With No Feedback
13. Accidental File Overwrite on Disk
14. PermissionError
15. Infinite Loop
16. Memory Error Scenario
17. Kernel Freeze Explanation and Prevention

---

Important Notes

About Kernel Restarts

Some errors require kernel restart to demonstrate properly. When instructed:

1. Click Kernel → Restart in menu
2. Re-run only the cells specified in instructions
3. Observe the error or behavior change

Safety Features

• No external downloads: All data is included
• No actual crashes: Dangerous operations are commented out with explanations
• Isolated errors: Each error is self-contained

---

Tips for Success

For Students

• Take your time—don't rush through errors
• Type fixes yourself rather than just uncommenting
• Experiment: try variations to deepen understanding
• Keep a "debugging cheatsheet" of common fixes

For Instructors

• Encourage students to explain errors to each other
• Use these as starting point for creating your own error examples
• Consider recording screencasts of debugging process
• Adapt difficulty by adding/removing explanations

---

Additional Resources

For Further Learning

• Jupyter Notebook Documentation
• Pandas User Guide
• Scikit-learn Tutorials
• Python Debugging Guide

---

Happy Debugging!

Remember: Every error is a learning opportunity. The best developers aren't those who never make mistakes—they're the ones who know how to fix them efficiently.