Error messages look alarming at first, but they're the most helpful thing Python does. Each one tells you what went wrong and exactly where. Once you can read them, most bugs take minutes instead of hours. This guide uses standard Python 3.13. MicroPython's messages are shorter but follow the same pattern.
How to read a traceback
When a program crashes, Python prints a traceback. Read it from the bottom up:
Traceback (most recent call last):
File "/home/pi/thermo.py", line 12, in <module>
show(reading)
~~~~^^^^^^^^^
File "/home/pi/thermo.py", line 6, in show
print("Temp: " + reading)
~~~~~~~~~^~~~~~~~~
TypeError: can only concatenate str (not "float") to str
- The last line is the error: its type,
TypeError, and a description. - The lines above show where: file, line number and the code itself. Newer Pythons underline the exact part that failed.
- Further up is how you got there. Line 12 called
show(), which failed on line 6. The bug is usually in the lowest line that's in your own code.
The errors you'll meet most
| Error | Example message | Usual cause and fix |
|---|---|---|
| SyntaxError | '(' was never closed | Python couldn't understand the code: a missing bracket, quote or colon. The real mistake is often on the line before the one reported. |
| IndentationError | expected an indented block after 'if' statement on line 1 | The lines inside an if, for or def must be indented. Use 4 spaces and don't mix tabs and spaces. |
| NameError | name 'pirnt' is not defined. Did you mean: 'print'? | A typo, or using a variable before it's created or outside the function it belongs to. |
| TypeError | can only concatenate str (not "int") to str | Mixing types. Use an f-string: f"Temp: {reading}". |
| ValueError | invalid literal for int() with base 10: '3.3' | Right type, wrong value. Here, use float() for text with a decimal point. |
| IndexError | list index out of range | Asking for item 3 of a 3-item list. Indexes start at 0, so the last is 2. |
| KeyError | 'b' | That key isn't in the dictionary. Use d.get("b") to get None instead of a crash. |
| AttributeError | 'str' object has no attribute 'append' | Calling a method the object doesn't have, often because a variable holds a different type than you think. |
| ZeroDivisionError | division by zero | Check the divisor first, for example when averaging an empty list. |
| ModuleNotFoundError | No module named 'smbuss' | A typo, or the library isn't installed for the Python you're running. Install it with pip or your system's package manager, inside the same virtual environment. |
On microcontrollers you'll also see OSError. With I²C on MicroPython, OSError: [Errno 5] EIO or ENODEV usually means the device didn't answer. Check the wiring, the power, the address and the pull-up resistors before the code. Our guide to I²C, SPI and UART covers the usual causes.
A debugging method that works
- Read the whole message. The answer is often in it, including the "Did you mean" hint.
- Reproduce it reliably. Find the smallest input or action that makes it fail.
- Check your assumptions with print. Print the values and their types just before the failing line:
print(repr(reading), type(reading)).reprshows hidden things such as a trailing\nfrom a sensor or serial port. - Change one thing at a time, and run again after each change.
- Cut it down. Comment out half the program. If the bug disappears, it's in the half you removed.
- Explain it out loud, line by line, to a person, a rubber duck or an AI model. You'll often spot it while explaining.
Catching errors you expect
Some failures are normal, such as a sensor that occasionally doesn't respond. Catch those specifically, so the program carries on, and let unexpected errors crash loudly so you notice them:
try:
reading = sensor.read()
except OSError:
print("Sensor didn't answer, trying again")
reading = None
Avoid a bare except:. It also catches typos and even Ctrl+C, hiding the very bugs you need to see.
Using AI to help debug
AI assistants are good at explaining errors. Paste the full traceback, the relevant code and what you expected to happen, not just "it doesn't work". Then check the suggested fix makes sense before you use it, because a confident answer isn't always a correct one. Our guide to why AI makes things up explains why.
Sources
The main references behind this guide. Numbers we worked out ourselves, such as the code outputs, come from running the code.