Course topics

By WebNest Studio Engineering Team

Python Tutorial

Raising Exceptions and Custom Exceptions

Handling errors is half the story; the other half is signalling them clearly. When a function receives invalid input or cannot do its job, it should raise an exception with a precise type and a helpful message, rather than returning None or -1 that callers might ignore.

This lesson covers the raise statement, re-raising, exception chaining with raise ... from, designing custom exception hierarchies for your application, adding data to exceptions, and notes with add_note().

Why it matters

Your own functions also need to report problems. Returning None or -1 for an error is easy to ignore and leads to failures far from the cause; raising an exception cannot be missed. Custom exception classes let callers handle your errors by name and carry the details needed to respond.

raise

raise ValueError("age must be positive") stops the function and sends the exception up the call stack until something handles it. Choose the most fitting built-in type: ValueError (right type, bad value), TypeError (wrong type), KeyError, LookupError, PermissionError, NotImplementedError, RuntimeError. A bare raise inside an except block re-raises the current exception after, for example, logging it.

Exception Chaining

When you catch a low-level error and raise a higher-level one, write raise NewError(...) from original. The traceback then shows both, with "The above exception was the direct cause of the following exception". Use from None to hide an irrelevant original error.

Custom Exceptions

Define your own exceptions by subclassing Exception. A good pattern is one base class for your application (ShopError) with specific subclasses (OutOfStockError, PaymentDeclinedError). Callers can then catch a specific error or all errors from your code at once. Custom exceptions can carry extra attributes such as an order id or an error code for API responses.

Adding Context with add_note()

Since Python 3.11, exception.add_note("...") attaches extra context that appears in the traceback — useful when re-raising errors while processing a particular file or record.

Examples

Raising built-in exceptions with clear messages

Python
def set_age(age):
    if not isinstance(age, int):
        raise TypeError(f"age must be an int, got {type(age).__name__}")
    if not 0 <= age <= 130:
        raise ValueError(f"age must be between 0 and 130, got {age}")
    return age

for value in [25, -3, "25"]:
    try:
        print("ok:", set_age(value))
    except (TypeError, ValueError) as e:
        print(f"{type(e).__name__}: {e}")
Output
ok: 25
ValueError: age must be between 0 and 130, got -3
TypeError: age must be an int, got str

Re-raising and exception chaining with from

Python
import json

class ConfigError(Exception):
    pass

def load_config(text):
    try:
        return json.loads(text)
    except json.JSONDecodeError as e:
        raise ConfigError("config file is not valid JSON") from e

try:
    load_config("{bad json")
except ConfigError as e:
    print("error:", e)
    print("caused by:", type(e.__cause__).__name__, "-", e.__cause__.msg)

def risky():
    try:
        1 / 0
    except ZeroDivisionError:
        print("logging the problem, then re-raising")
        raise

try:
    risky()
except ZeroDivisionError as e:
    print("caller received:", e)
Output
error: config file is not valid JSON
caused by: JSONDecodeError - Expecting property name enclosed in double quotes
logging the problem, then re-raising
caller received: division by zero

A custom exception hierarchy with extra data

Python
class ShopError(Exception):
    """Base class for all shop errors."""

class OutOfStockError(ShopError):
    def __init__(self, item, requested, available):
        super().__init__(f"only {available} {item}(s) left, {requested} requested")
        self.item, self.requested, self.available = item, requested, available

class PaymentDeclinedError(ShopError):
    def __init__(self, reason, code="CARD_DECLINED"):
        super().__init__(reason)
        self.code = code

stock = {"hoodie": 2}

def buy(item, qty, card_ok=True):
    if stock.get(item, 0) < qty:
        raise OutOfStockError(item, qty, stock.get(item, 0))
    if not card_ok:
        raise PaymentDeclinedError("insufficient balance")
    stock[item] -= qty
    return "order placed"

for args in [("hoodie", 1), ("hoodie", 5), ("hoodie", 1, False)]:
    try:
        print(buy(*args))
    except OutOfStockError as e:
        print("stock:", e, "| available =", e.available)
    except ShopError as e:
        print(f"shop error [{getattr(e, 'code', '-')}]:", e)
Output
order placed
stock: only 1 hoodie(s) left, 5 requested | available = 1
shop error [CARD_DECLINED]: insufficient balance

Adding context with add_note()

Python
rows = ["10", "20", "abc", "40"]
try:
    for line_no, row in enumerate(rows, start=1):
        try:
            int(row)
        except ValueError as e:
            e.add_note(f"while processing line {line_no} of marks.csv")
            raise
except ValueError as e:
    print(e)
    print(e.__notes__)
Output
invalid literal for int() with base 10: 'abc'
['while processing line 3 of marks.csv']

Common Mistakes

  • Returning None or -1 for errors instead of raising, so failures go unnoticed.
  • Raising the generic Exception instead of a specific type.
  • Raising a new exception inside except without "from", losing or confusing the original cause.
  • Deriving custom exceptions from BaseException instead of Exception.

Exercise

Define a custom exception InsufficientFunds that stores the balance and the amount requested. withdraw should raise it when the amount exceeds the balance. The caller catches it and prints how much is missing, then whether the error is an Exception.

Expected output: Short by 50 then True

Python · starter code
# TODO: class InsufficientFunds(Exception) storing balance and amount


def withdraw(balance, amount):
    # TODO: raise InsufficientFunds when amount > balance
    return balance - amount


try:
    withdraw(100, 150)
except InsufficientFunds as error:
    print(f"Short by {error.amount - error.balance}")
    print(isinstance(error, Exception))
Show hints
  • Give the class an __init__(self, balance, amount) that stores both and calls super().__init__(...) with a message.
  • Raise it with raise InsufficientFunds(balance, amount).
Show solution
Python · solution
class InsufficientFunds(Exception):
    def __init__(self, balance, amount):
        super().__init__(f"cannot withdraw {amount} from {balance}")
        self.balance = balance
        self.amount = amount


def withdraw(balance, amount):
    if amount > balance:
        raise InsufficientFunds(balance, amount)
    return balance - amount


try:
    withdraw(100, 150)
except InsufficientFunds as error:
    print(f"Short by {error.amount - error.balance}")
    print(isinstance(error, Exception))

Quick quiz

1. Which class should a custom exception inherit from?

  • A. BaseException
  • B. Error
  • C. object
  • D. Exception
Show answer

D. BaseException is reserved for things like KeyboardInterrupt and SystemExit.

2. What does a bare raise inside an except block do?

  • A. Raises a new empty exception
  • B. Re-raises the exception that is being handled
  • C. Ends the program silently
  • D. Nothing
Show answer

B. It is used to log an error and still let it propagate.

3. What does raise AppError("failed") from original do?

  • A. Discards the original exception
  • B. Records the original as the cause, so both appear in the traceback
  • C. Raises both at once
  • D. It is a syntax error
Show answer

B. The original is stored in the __cause__ attribute of the new exception.

Interview questions

Why create custom exception classes?

Show answer

They let callers catch the errors of your code specifically, without also catching unrelated ones, and they can carry extra data such as an error code or the offending value. A library usually defines one base exception and derives the others from it, so a caller can catch a single case or everything the library raises with one except.

What is exception chaining?

Show answer

When an exception is raised while another is being handled, Python links them. raise NewError(...) from original does this explicitly and sets __cause__, and the traceback shows both with "The above exception was the direct cause". It is used to convert a low-level error, such as a database error, into one that is meaningful to the caller without losing the original details.

Key Points to Remember

  • raise SpecificError("clear message") signals problems precisely.
  • A bare raise re-raises the current exception.
  • raise New(...) from original chains exceptions and keeps the cause.
  • Build custom exception hierarchies from Exception, with extra attributes when useful.
  • add_note() attaches extra context (3.11+).

Practice in the playground

Write and run your own code for this topic, or start from the exercise or an example. Runs Python in your browser. Your code for each topic is kept in this browser.

Run the examples

Change an input, predict the result, then compare it with the output. Explain why the result changes.

WebNest Studio

Written by

WebNest Studio Engineering Team

Practical lessons from developers working with Java, Python, React, databases and production systems.

Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering