Errors & Debugging

Module 07 taught the bottom-up reading. This is the reference: what each part of a traceback is, including the pieces newer Python versions added — the ^^^^ markers that point at the exact expression, the "Did you mean" suggestions, and the chained "During handling of the above exception" blocks.

Traceback (most recent call last):            ① header — frames follow, outermost first
  File "app.py", line 22, in main            ② a frame: file, line, function
    total = process(rows)                    ③ the source line of that frame
  File "app.py", line 12, in process
    return row["price"] * qty
           ~~~^^^^^^^^^                      ④ 3.11+: exactly which expression failed
KeyError: 'price'                            ⑤ the exception type and message — START HERE

The above exception was the direct cause of the following exception:   ⑥ chaining (raise … from e)

Traceback (most recent call last):
  ...
PricingError: could not price row 4          ⑦ the outer, higher-level error your code raised

• Read ⑤ first, then find the last frame that is in your file, then look at ③/④ on that frame.
• A SyntaxError or IndentationError has no frames — it happened before the program ran — and the caret points at (or just after) the problem.
• "During handling of the above exception, another exception occurred" means your except block itself crashed. Fix the second one first; it is hiding the first.
• 3.10+ adds Did you mean: 'total'? to NameError and AttributeError. Trust it.

Every error below is one you will meet in your first month. Each card is the same shape: the code that causes it, the traceback, why the interpreter said it, and the fix. Errors already covered in earlier modules are summarised with a link; the rest are here in full. Bookmark this page.

total = sum([1, 2, 3]
print(total)

  File "your code", line 1
    total = sum([1, 2, 3]
                ^
SyntaxError: '(' was never closed

total = sum([1, 2, 3])
print(total)

count = 5
print(count[0])          # not subscriptable
# for x in count: ...   # would be: 'int' object is not iterable
# count()               # would be: 'int' object is not callable

Traceback (most recent call last):
  File "your code", line 2, in <module>
    print(count[0])
TypeError: 'int' object is not subscriptable

counts = [5]
print(counts[0])

price = int("12.5")

Traceback (most recent call last):
  File "your code", line 1, in <module>
    price = int("12.5")
ValueError: invalid literal for int() with base 10: '12.5'

price = int(float("12.5"))   # 12 — or keep it a float
print(price)

def find_user(users, name):
    for u in users:
        if u == name:
            return u
    # falls off the end → returns None

user = find_user(["ada", "linus"], "grace")
print(user.upper())

Traceback (most recent call last):
  File "your code", line 8, in <module>
    print(user.upper())
AttributeError: 'NoneType' object has no attribute 'upper'

def find_user(users, name):
    for u in users:
        if u == name:
            return u
    return None       # explicit: callers know to check

user = find_user(["ada", "linus"], "grace")
print(user.upper() if user else "no such user")

scores = []
average = sum(scores) / len(scores)

Traceback (most recent call last):
  File "your code", line 2, in <module>
    average = sum(scores) / len(scores)
ZeroDivisionError: division by zero

scores = []
average = sum(scores) / len(scores) if scores else 0
print(average)

Print debugging is legitimate — every professional does it. Do it well: print the name and the type along with the value, and use the f-string = form so you never mislabel. Then, in any program that runs unattended, replace prints with logging: it adds timestamps, levels you can filter, and goes to a file or a log service instead of the screen.

When prints are not enough, stop the program and look around. breakpoint() anywhere in your code drops you into pdb, the built-in debugger, at that line: you can print any variable, step line by line, and continue. It does not work in this page (there is no terminal to type into), so this lesson is for your machine — but it is worth the five minutes to learn, and VS Code's graphical debugger is the same thing with buttons.

def summarise(rows):
    total = 0
    for row in rows:
        breakpoint()            # execution stops here, every iteration
        total += row["amount"]
    return total

print(summarise([{"amount": 5}, {"amount": "7"}]))

$ python3 report.py
> report.py(5)summarise()
-> total += row["amount"]
(Pdb) p row                      # print a variable
{'amount': 5}
(Pdb) p total, type(row["amount"])
(0, <class 'int'>)
(Pdb) n                          # next line
(Pdb) c                          # continue to the next breakpoint (next iteration)
> report.py(5)summarise()
(Pdb) p row
{'amount': '7'}                  # ← there it is: a string
(Pdb) q                          # quit

Most real tracebacks are forty lines long and thirty of them are inside pandas, requests or a framework. The rule does not change: the error message at the bottom says what; the last frame in your own file says where you caused it. The library frames between them tell you what the library was trying to do with your input — read them once, then ignore them.

Traceback (most recent call last):
  File "etl.py", line 44, in <module>
    main()
  File "etl.py", line 31, in main
    df = load_orders("orders.csv")
  File "etl.py", line 18, in load_orders                          ← ★ your last frame: line 18
    return pd.read_csv(path, parse_dates=["created"])
  File ".../site-packages/pandas/io/parsers/readers.py", line 1026, in read_csv
    return _read(filepath_or_buffer, kwds)
  File ".../site-packages/pandas/io/parsers/readers.py", line 620, in _read
    parser = TextFileReader(filepath_or_buffer, **kwds)
  ... 6 more pandas frames ...
  File ".../site-packages/pandas/io/parsers/c_parser_wrapper.py", line 93, in __init__
    self._reader = parsers.TextReader(src, **kwds)
  File "parsers.pyx", line 581, in pandas._libs.parsers.TextReader.__cinit__
ValueError: Missing column provided to 'parse_dates': 'created'   ← ★ what: the CSV has no "created" column

Two lines out of eighteen. Your line 18 passed parse_dates=["created"]; the file does not have that column. Print pd.read_csv(path, nrows=0).columns and look.

• Search the exact error message in quotes. Library errors are shared by thousands of people; the first result is usually a GitHub issue with the answer.
• Check the library version: pip show pandas. Half of "this worked yesterday" is an upgrade.
• Reproduce in three lines in the REPL with the same input. If it still fails, you have a minimal example — the thing every bug report and every AI tutor needs.
• When the traceback ends inside a .pyx or C extension, the useful frame is the Python one just above it.

Code that runs for you and fails for a colleague, in CI, or on the server is almost never a Python bug. It is one of a short list of environment differences. Work through them in order; the answer is usually in the first three.

1. 1
   Which Python?

   python3 --version and which python3 on both machines. 3.9 versus 3.12 changes syntax (match, X | Y hints) and behaviour.

2. 2
   Which packages, which versions?

   pip freeze on both and diff them. This is what requirements.txt with pinned versions exists to prevent.

3. 3
   Which working directory?

   Relative paths resolve against where python was run from. CI runs from the repo root; you ran from src/. Use Path(__file__).parent.

4. 4
   Which environment variables?

   API keys, DATABASE_URL, PYTHONPATH. Print os.environ.get("X") at startup; missing on the server means None.

5. 5
   Which OS?

   Case-sensitive filenames on Linux, \ vs /, line endings, the default file encoding (always pass encoding="utf-8"), and timezone of the machine clock.

6. 6
   Which data?

   Your local test file has 100 clean rows; production has 10 million and one of them has a null. Test with a sample of the real thing.

7. 7
   Stale state?

   An old .pyc, a cached result, a leftover file from a previous run. Delete __pycache__ and the output directory and run once more.