Python assert — Production Data Silently Corrupted by -O

Every program you write makes assumptions — that a user's age is positive, that a file actually exists, that a payment amount isn't zero. When those assumptions break, your program shouldn't silently limp along producing garbage output. It should fail loudly, clearly, and in a way that points directly at the problem. That's exactly what raise and assert are built for, and knowing the difference between them is what separates defensive code from fragile code.

The real problem isn't that Python will crash when things go wrong — it's that without raise and assert, it often crashes in the wrong place, showing you a confusing error three function calls away from where the actual bug lives. These two tools let you put guardrails exactly where your assumptions live, so when something breaks, the error message is a signpost, not a riddle.

By the end of this article you'll know how to raise built-in and custom exceptions with meaningful messages, how to use assert as a development-time safety net, why you should never use assert to validate user input, and how to chain exceptions to preserve debugging context. You'll be writing code that fails helpfully instead of mysteriously.

raise — Telling Python Something Has Gone Wrong

raise is how you deliberately trigger an exception. You're not waiting for Python to stumble — you're the one blowing the whistle because you've already detected the problem.

The basic form is raise ExceptionType("your message"). The exception type tells Python (and the developer reading the traceback) what kind of problem occurred. The message tells them what the specific problem was. Both matter — a ValueError with the message "age must be a positive integer, got -3" is infinitely more useful than a generic crash.

Python has a rich built-in exception hierarchy. Choosing the right type isn't just cosmetic — it lets callers catch specific exceptions without catching everything. Use ValueError when a value is the wrong kind. Use TypeError when the wrong type was passed. Use RuntimeError when something goes wrong that doesn't fit a neater category. Using the right exception type is a form of documentation.

You can also raise inside an except block to re-raise after logging, or to wrap a low-level exception in a higher-level one that makes more sense to the caller.

def register_user(username: str

Custom Exceptions — Making raise Even More Powerful

Built-in exceptions are great, but they're generic. When you're building a library, an API client, or any system with its own domain logic, callers need to distinguish your errors from Python's built-in ones.

Creating a custom exception is just one line: subclass Exception (or a more specific built-in). That's it. You've now given your package its own exception namespace. Callers can except PaymentError and know they're handling your domain problem, not some random ValueError from an unrelated library.

The real power is in the hierarchy. A payment system might have a base PaymentError, with InsufficientFundsError and CardDeclinedError as subclasses. Callers who care about both can catch PaymentError. Callers who need to handle each case differently can catch the subclass. This is the same design Python itself uses — you can catch OSError for any file system problem, or FileNotFoundError specifically.

Add raise ... from original_error (exception chaining) when you're wrapping a low-level exception. This preserves the original traceback so debugging context is never lost — a sign of professional-grade code.

def calculate_weighted_average(values: list

raise vs assert — Choosing the Right Tool for the Job

The confusion between raise and assert is one of the most common intermediate-level mistakes in Python. They look similar — both stop execution when something is wrong — but they exist for completely different reasons and different audiences.

raise is for runtime conditions that can legitimately happen in production and that your code needs to handle gracefully. Bad user input, missing files, network failures, invalid API responses — these aren't bugs, they're expected failure modes. raise communicates the problem to the caller so they can decide what to do next.

assert is for invariants that should never be false if your code is correct. It's a communication tool between developers, not a runtime guard. It says: "I wrote this function assuming X is always true here. If X is ever false, the logic of this program is broken and we need to fix the code, not handle the error."

A useful mental model: raise handles the unexpected-but-possible. assert documents the impossible. If you find yourself writing assert to handle something that a user, file, or network could cause — swap it for raise. If you find yourself catching AssertionError in production code — that's a red flag that you've misused assert.

import json

# ============================================================
# raise: for conditions that can happen legitimately at runtime
# ============================================================

def load_product_catalog(filepath: str) -> dict:
    try:
        with open(filepath, "r") as file:
            catalog = json.load(file)
    except FileNotFoundError:
        raise FileNotFoundError(
            f"Product catalog not found at '{filepath}'. Check the path and ensure the file was deployed."
        )
    except json.JSONDecodeError as parse_error:
        raise ValueError(
            f"Catalog file at '{filepath}' contains invalid JSON."
        ) from parse_error
    return catalog


def apply_discount(product: dict

Exception Chaining — raise X from Y Preserves the Full Story

When you catch a low-level exception and raise a domain-specific one, you have a choice: lose the original traceback or preserve it. A bare raise MyError('msg') discards the original exception entirely. raise MyError('msg') from original_error chains them — the traceback shows both exceptions, with 'The above exception was the direct cause of the following exception' linking them.

This is crucial for debugging. Without chaining, you see PaymentError and have to guess the root cause. With chaining, you see not only that the payment failed (PaymentError) but also why (KeyError because account was missing from the database). Exception chaining is a hallmark of production-grade error handling.

Python supports implicit chaining as well: when a new exception is raised while an exception is already active, Python automatically sets the __context__ attribute. But explicit chaining with from is preferred because it makes the causal relationship intentional and clear to readers.

import json

# --- Custom exceptions ---
class ConfigError(Exception):
    """Base for all configuration errors."""
    pass

class ConfigParseError(ConfigError):
    """Raised when a config file cannot be parsed."""
    pass

class ConfigMissingError(ConfigError):
    """Raised when a required config key is missing."""
    pass


# --- Function that demonstrates proper chaining ---

def load_app_config(filepath: str) -> dict:
    try:
        with open(filepath) as f:
            config = json.load(f)
    except FileNotFoundError as fnf:
        raise ConfigError(f"Configuration file '{filepath}' not found") from fnf
    except json.JSONDecodeError as je:
        raise ConfigParseError(f"Invalid JSON in '{filepath}'") from je

    # Validate required keys
    if 'database_url' not in config:
        raise ConfigMissingError(
            "Config must contain 'database_url'"
        )

    return config


# --- Without chaining (bad) vs with chaining (good) ---

print("=== With chaining (raise ... from) ===")
try:
    load_app_config("nonexistent.json")
except ConfigError as e:
    print(repr(e))
    print(f"Cause: {e.__cause__}")

print("\n=== Without chaining (bare raise) — compare ===")
try:
    # Simulate bad pattern
    try:
        with open("nonexistent.json") as f:
            pass
    except FileNotFoundError as fnf:
        raise ConfigError("Config file not found")  # No 'from' — bad!
        # Raises ConfigError without linking the original error
except ConfigError as e:
    print(repr(e))
    print(f"Cause (missing): {e.__cause__}")

Frequently Asked Questions