Skip to content
Tutorials Center
My learning

Topics

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").

TEXT
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

Python Catch a traceback and print 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.

Python The exception object holds the same information

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.

Python Chained exceptions: cause and context

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 explicit raise ... from err. The first error is the cause.
  • During handling of the above exception, another exception occurred: means a new error was raised inside an except block. 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 a None that 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() or logging.exception("...") inside except to 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, or err.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 use pdb (see the debugging lesson).