Troubleshooting guide

A reliable debugging process

1. Read the last line of the error first.
2. Find the line in your code named by the traceback.
3. Compare the actual value with the value you expected.
4. Reproduce the smallest failing example.
5. Change one thing.
6. Run again and record what changed.

Do not delete the whole project or randomly reinstall packages before identifying the failure.

Common problems

Symptom	Likely cause	First action
python: command not found	Python is not installed or not on PATH	Try python3 --version, then follow the official Python installation guide.
ModuleNotFoundError	Package is missing from the active environment	Activate .venv, then install the named package with python -m pip install package-name.
Notebook cells use old values	Kernel state is out of order	Restart the kernel and run all cells from the top.
NameError	A name was misspelled or its defining cell did not run	Check spelling and run the setup cell.
TypeError	An operation received the wrong kind of value	Print the values and their types with type(value).
Empty chart	Data is empty or the plot was not displayed	Print the data and run plt.show().
API authentication failure	Missing, expired, or incorrectly named environment variable	Check the variable name without printing the secret.
Git merge conflict	Two edits changed the same lines	Read both versions, choose deliberately, then commit the resolution.

Ask for help well

Include:

• the lesson and step;
• the smallest code that fails;
• the complete error message;
• what you expected;
• what you already tried;
• your operating system and Python version.

Never include passwords, API keys, private student data, or full secret environment files.

Resetting a notebook

When results seem inconsistent:

1. Save useful notes.
2. Restart the kernel.
3. Run all cells in order.
4. Remove hidden state and unused imports.
5. Recheck the smallest example.

Further reading

• Python errors and exceptions
• Jupyter notebook workflow
• Git documentation