Debugging Tracebacks

diagram read a traceback from the bottom mermaid

  flowchart TD
  A["Traceback (most recent call last):"] --> B["outermost frame -- where the call chain began"]
  B --> C["... intermediate frames ..."]
  C --> D["innermost frame -- the line that raised"]
  D --> E["ExceptionType: message"]
  E --> F["1. read the type and message FIRST"]
  F --> G["2. find the lowest frame in YOUR code"]
  G --> H["3. walk up only if that frame looks correct"]
  I["'During handling ... another exception occurred'"] --> J["two tracebacks: the second one is the cause"]
  K["'The above exception was the direct cause'"] --> L["raise ... from -- read the FIRST block"]

The frames are printed in call order -- where it started at the top, where it exploded at the bottom -- and the exception itself is the last line. So the fastest way to read one is to start at the bottom, find the error type and the innermost frame, and only walk upwards if that frame is not yours.

Frame order, verified

For a() calling b() calling c(), which raises:

text

Traceback (most recent call last):
  File "<stdin>", line 17, in <module>     <- where it started
  File "<stdin>", line 14, in a
  File "<stdin>", line 15, in b
  File "<stdin>", line 16, in c            <- where it was RAISED
ValueError: boom                           <- what went wrong

The header says it: most recent call last. The bottom is the interesting end.

For a long traceback through a framework, the practical trick is to scan upward from the bottom for the first frame in a file you wrote. Everything below it is usually library code doing what it was told, and the mistake is normally in your frame or in the arguments it passed.

When two tracebacks are printed, the phrasing between them tells you which to read first: “During handling of the above exception, another exception occurred” means the second one is incidental, while “The above exception was the direct cause” means the first one is the real story.

A repeatable debugging process

When you see an exception:

1. Read the last line (exception type + message)
2. Go to the line number where it occurred
3. Check the types/values of variables
4. Create a minimal reproduction
5. Fix and re-run

Example traceback

bug.py

def avg(nums):
    return sum(nums) / len(nums)
 
print(avg([]))

Traceback

Traceback (most recent call last):
  File "bug.py", line 4, in <module>
    print(avg([]))
  File "bug.py", line 2, in avg
    return sum(nums) / len(nums)
ZeroDivisionError: division by zero

Fix approach

• The list is empty, so len(nums) is 0.
• Decide policy: return None, raise a clear error, or handle with default.

fix.py

def avg(nums):
    if len(nums) == 0:
        raise ValueError("avg() requires at least one number")
    return sum(nums) / len(nums)
 
print(avg([10, 20]))

Quick tip: print types

type_debug.py

value = "10"
print(type(value), value)
print(int(value))

Optional: use the debugger

Python has a built-in debugger.

pdb_example.py

import pdb
 
x = 10
pdb.set_trace()
print(x)

Useful commands inside the debugger:

• n next
• s step into
• p var print variable
• c continue

sketch Read a traceback from the bottom p5.js Pause Restart

The frames are printed in call order, so where it started is at the top and where it exploded is at the bottom, with the exception itself on the last line. Scanning upward from the bottom for the first frame in code you wrote is the fastest route to the mistake, because everything below that is usually a library doing what it was told.

Check yourself

pch.quizTag pch.quizDefaultTitle

1. In a Python traceback, which line tells you where the exception was RAISED?

   A The first `File` line B The last `File` line, just above the exception message C The line after `Traceback` D It is not shown
   pch.quizShowAnswer

   B — The last `File` line, just above the exception message — The header says 'most recent call last'. Frames are printed in call order, so the bottom frame is the innermost one.

2. A traceback runs through twenty frames of a web framework. What is the fastest way in?

   A Read from the top B Read the exception line, then scan up for the lowest frame in your own code C Search for the word 'error' D Re-run with a debugger
   pch.quizShowAnswer

   B — Read the exception line, then scan up for the lowest frame in your own code — Everything below your lowest frame is usually library code doing what it was told. The mistake is normally in your frame or in the arguments it passed.

3. Two tracebacks are printed with 'During handling of the above exception, another exception occurred' between them. What does that mean?

   A The first is the real cause B The second happened while handling the first, and is often incidental C They are unrelated D The program crashed twice
   pch.quizShowAnswer

   B — The second happened while handling the first, and is often incidental — That phrasing means implicit chaining via `__context__`. 'The above exception was the direct cause' is the other one — deliberate chaining with `raise ... from`, where the first block is the story.

4. Why does `raise ... from None` not actually erase the original exception?

   A It does erase it B It only suppresses the DISPLAY; `__context__` is still set C It converts it to a warning D It re-raises it later
   pch.quizShowAnswer

   B — It only suppresses the DISPLAY; `__context__` is still set — Verified: after `from None`, `__cause__` is None but `__context__` still holds the original. A logger walking the chain can still find it.

🧪 Try It Yourself

Exercise 1 – Read a Traceback

pch.exerciseTag pch.exerciseTitle

Exercise 2 – Traceback Module

pch.exerciseTag pch.exerciseTitle

Exercise 3 – Get Traceback as String

pch.exerciseTag pch.exerciseTitle