Visual walkthrough — Exception hierarchy

This is the deep-dive companion to the parent Exception Hierarchy note. If you have never met try/except, read 1.3.06-TryExcept-Finally first — but you can follow every line here from scratch.

Before we can talk about a "family tree" of errors, we need two plain-English words nailed down.

Step 1 — Draw the family tree (this is the whole game board)

WHAT. Every error type in Python sits somewhere in one giant tree. At the very top is ==BaseException==. Everything else hangs below it.

WHY. A tree gives us exactly one path from any error up to the top. That single upward path is what Python will search when it hunts for a matching except. No tree ⇒ no rule.

PICTURE. Follow the arrows upward. Each arrow means "is a".

Read the picture:

• BaseException — the ultimate ancestor. Catching it catches literally everything.
• Three "special" siblings hang directly off it: ==SystemExit== (from sys.exit()), ==KeyboardInterrupt== (you pressed Ctrl+C), GeneratorExit. These are not ordinary bugs — they are "please shut down" signals.
• Exception — where ordinary errors live. Below it: ArithmeticError, LookupError, OSError, and dozens more.

Step 2 — One error, one upward path

WHAT. Suppose the running code raises KeyError('age') — you asked a dictionary for a key it does not have. We trace the only path from KeyError up to the top.

WHY. Python's search only ever moves upward along this path. It never sideways, never down. If we know the path, we can predict every catch. So let's isolate it.

PICTURE. The one path, lit up in orange:

The lit path, bottom to top, is:

$\underset{\text{the actual error raised}}{\underbrace{\text{KeyError}}}\to \underset{\text{parent}}{\underbrace{\text{LookupError}}}\to \underset{\text{grandparent}}{\underbrace{\text{Exception}}}\to \underset{\text{top ancestor}}{\underbrace{\text{BaseException}}}$

• The first name is the type of the error that happened.
• Each → is read "is a": a KeyError is a LookupError, which is an Exception, which is a BaseException.
• Anything not on this line — say ZeroDivisionError — can never catch our KeyError. It is on a different branch.

KeyError is-a LookupError? ::: Yes — LookupError is directly above it on the path. KeyError is-a ArithmeticError? ::: No — ArithmeticError is on a different branch, not on KeyError's upward path.

Step 3 — The matching rule, stated exactly

WHAT. Now the actual rule Python uses.

WHY. "First one on the path wins" is the entire behaviour. Everything else on this page is a consequence of this single line.

PICTURE. Left column = your except list, top to bottom. We test each against the lit path from Step 2 and stop at the first hit.

Here the handlers are except IndexError → except LookupError → except Exception.

• $H_1=$ IndexError: is KeyError an IndexError? Look at the path — IndexError is not on it. ❌ skip.
• $H_2=$ LookupError: on the path? Yes. ✅ STOP — this block runs.
• $H_3=$ Exception: never even tested, because we already stopped.

Step 4 — Why "specific before general" is a law, not a style tip

WHAT. We put a general handler above a specific one, and watch the specific one die.

WHY. Because the rule says "first match on the path wins," a handler that is higher up the tree is a bigger net. Put the big net first and it scoops the error before the small net gets a turn.

PICTURE. Both Exception and KeyError are on the path — but Exception is written first, so it wins, and except KeyError becomes dead code.

try:
    data[key]                # raises KeyError
except Exception as e:       # H1: Exception IS on KeyError's path → wins immediately
    print("General error")
except KeyError as e:        # H2: never reached — dead code
    print("Key missing")

The safe ordering — deepest node first, then walk up:

try:
    data[key]
except KeyError as e:        # deepest → checked first
    print(f"Missing key: {e}")
except LookupError as e:     # its parent → catches siblings like IndexError
    print(f"Lookup failed: {e}")
except Exception as e:       # grandparent → safety net for anything else
    print(f"Unexpected: {e}")

Step 5 — One handler for two errors (exploit a shared parent)

WHAT. A list lookup can raise IndexError; a dict lookup can raise KeyError. We want to catch both with one except.

WHY. Look back at Step 1: IndexError and KeyError are siblings — they share the parent LookupError. So LookupError sits on both their upward paths. One handler at the parent catches both children.

PICTURE. Two different errors, two different upward paths — but the paths merge at LookupError. Catching there covers both.

def process_user_data(data, index, key):
    try:
        item  = data[index]      # may raise IndexError
        value = item[key]        # may raise KeyError
        return value
    except LookupError as e:     # sits on BOTH paths → catches either child
        print(f"Data lookup failed: {e}")
        return None
 
process_user_data([{'name': 'Alice'}], 0, 'name')  # -> 'Alice'
process_user_data([{'name': 'Alice'}], 5, 'name')  # IndexError -> LookupError handler -> None
process_user_data([{'name': 'Alice'}], 0, 'age')   # KeyError  -> LookupError handler -> None

Use this only when you want the same recovery for both. If you need different messages, go back to two child handlers (Step 4 ordering).

Step 6 — The degenerate case: BaseException vs Exception (Ctrl+C)

WHAT. The edge case everyone gets bitten by. You press Ctrl+C to kill a stuck program. Python turns that keypress into a KeyboardInterrupt. Which handlers catch it?

WHY. KeyboardInterrupt hangs directly off BaseException — it is NOT below Exception (re-read Step 1!). So its upward path is short and skips Exception entirely:

$\text{KeyboardInterrupt}\to \text{BaseException}$

PICTURE. The Ctrl+C path (left) never touches Exception. So except Exception misses it — good, your Ctrl+C works — while except BaseException swallows it — bad, your program refuses to die.

• except Exception: → Exception is not on the KeyboardInterrupt path → does not catch Ctrl+C. ✅ The program still exits when you hit Ctrl+C.
• except BaseException: → BaseException is on the path → catches Ctrl+C → your loop keeps running forever. ❌

Which shutdown signals live directly under BaseException, not under Exception? ::: SystemExit, KeyboardInterrupt, GeneratorExit

Step 7 — The other degenerate case: no handler matches

WHAT. What if the error's upward path contains none of your handler types?

WHY. The rule from Step 3 finds "the first $H_i$ on the path". If there is no such $H_i$, the search reaches the top with no match — Python gives up on this try and re-raises the error to the code that called you. If nobody up the call stack catches it either, the program crashes with a traceback.

PICTURE. The path is walked to BaseException, every handler misses, and the error escapes the try block entirely.

try:
    1 / 0                    # ZeroDivisionError
except KeyError:             # KeyError not on ZeroDivisionError's path
    ...                      # no match anywhere -> error propagates -> crash

The takeaway: a try/except only protects you against errors whose type is on the path of one of your handlers. Everything else sails straight through. This is why you sometimes want a final except Exception safety net — it sits on every ordinary error's path.

The one-picture summary

Everything compressed: an error is born at some node; Python lights its upward path; it scans your except list top to bottom; the first handler that lies on the lit path wins; parents are bigger nets (put them last); the three shutdown signals sit off to the side under BaseException where except Exception cannot reach them.

Ready to build your own nodes on this tree? See 1.3.08-Custom-Exceptions.