Home / Learn / Code for makers

How to read Python error messages and fix your code

A Python traceback in a terminal, with the final error line highlighted as the place to start reading
Beginner

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
  1. The last line is the error: its type, TypeError, and a description.
  2. The lines above show where: file, line number and the code itself. Newer Pythons underline the exact part that failed.
  3. 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

ErrorExample messageUsual cause and fix
SyntaxError'(' was never closedPython couldn't understand the code: a missing bracket, quote or colon. The real mistake is often on the line before the one reported.
IndentationErrorexpected an indented block after 'if' statement on line 1The lines inside an if, for or def must be indented. Use 4 spaces and don't mix tabs and spaces.
NameErrorname '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.
TypeErrorcan only concatenate str (not "int") to strMixing types. Use an f-string: f"Temp: {reading}".
ValueErrorinvalid literal for int() with base 10: '3.3'Right type, wrong value. Here, use float() for text with a decimal point.
IndexErrorlist index out of rangeAsking 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.
ZeroDivisionErrordivision by zeroCheck the divisor first, for example when averaging an empty list.
ModuleNotFoundErrorNo 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

  1. Read the whole message. The answer is often in it, including the "Did you mean" hint.
  2. Reproduce it reliably. Find the smallest input or action that makes it fail.
  3. Check your assumptions with print. Print the values and their types just before the failing line: print(repr(reading), type(reading)). repr shows hidden things such as a trailing \n from a sensor or serial port.
  4. Change one thing at a time, and run again after each change.
  5. Cut it down. Comment out half the program. If the bug disappears, it's in the half you removed.
  6. 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.