Python Reference ยท Practical Pages
Reading Python tracebacks
Concept page on reading Python tracebacks: read bottom to top, understand the error type and message, chained exceptions, and how to catch and print them.
When an exception is not handled, Python stops and prints a traceback: a report of where the error happened and how the program got there. It looks intimidating, but it has a fixed layout and the answer is almost always in the last line and the last frame.
The golden rule: read from the bottom up. The last line names the exception type and message ("what went wrong"). The lines just above it show the exact line of code that raised it ("where"). The frames above that show the chain of calls that led there ("how we got here").
Traceback (most recent call last):
File "main.py", line 9, in <module>
total = average([])
File "main.py", line 5, in average
return sum(values) / len(values)
ZeroDivisionError: division by zero
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Anatomy of a traceback
| Part | What it tells you |
|---|---|
Traceback (most recent call last): |
Frames are listed oldest first; the newest is at the bottom. |
File "x.py", line 5, in average |
File, line number and function of that frame. |
| the indented source line | The statement that was running. Newer versions add ^^^^ markers under the failing part of the line. |
ZeroDivisionError: division by zero |
The exception class and its message. |
Python 3.13 and later also colors tracebacks in a terminal. In the browser runner you see plain text.
Chained tracebacks
Two messages can appear in one report:
The above exception was the direct cause of the following exception:means an explicitraise ... from err. The first error is the cause.During handling of the above exception, another exception occurred:means a new error was raised inside anexceptblock. The first error is the context; it may be a bug in your handler.
Read the bottom exception first, then look up for its cause. raise ... from None hides the chain on purpose.
Common first lines and what they usually mean
NameError: a typo, or the name was never defined in this scope.TypeError: the wrong type or argument count for an operation or call.ValueError: the right type, but an unacceptable value (int("abc")).KeyError/IndexError: a missing dict key or an out-of-range position.AttributeError: the object has no such attribute; often aNonethat came back from a function that returned nothing.ImportError/ModuleNotFoundError: the module is not installed or the name is wrong.SyntaxError/IndentationError: the file cannot even be parsed; the reported line may be just after the real mistake (an unclosed bracket, a missing colon).RecursionError: a function calls itself without reaching a base case.
Usage notes
- A very long traceback (hundreds of repeated frames) means recursion. Python shortens it with a "[Previous line repeated N more times]" note.
- Errors in code you did not write usually come from your call into a library. Find the lowest frame in your own file; that is the call to examine.
- Use
traceback.print_exc()orlogging.exception("...")insideexceptto record a full traceback without crashing. - Do not catch bare
except:and swallow errors; you lose the traceback that would have explained the bug. - Add context with
raise NewError("what you were doing") from err, orerr.add_note("details")(Python 3.11+), which prints under the message. - Since 3.10 error messages suggest fixes: "Did you mean: ..." for misspelled names and attributes.
- For step-by-step investigation, set a breakpoint with
breakpoint()and usepdb(see the debugging lesson).
Related
- Exception hierarchy, Exception chaining, try / except
- ValueError, TypeError, KeyError
- Tutorial lessons: Exceptions, Debugging, Logging and warnings