Raising & Chaining

Translate low-level failures into domain errors without losing context. Use raise ... from, bare raise, and from None intentionally so tracebacks tell the full story.

Recipe

def load_user(user_id: str) -> dict:
    try:
        return fetch_row(user_id)
    except KeyError as exc:
        raise UserNotFoundError(user_id) from exc

When to reach for this:

• Wrapping third-party exceptions at API boundaries
• Adding business context while preserving root cause
• Suppressing noisy intermediate tracebacks (from None)
• Logging then re-raising with bare raise
• Chaining validation errors in layered architectures

Working Example

class UserNotFoundError(LookupError):
    def __init__(self, user_id: str) -> None:
        self.user_id = user_id
        super().__init__(f"user not found: {user_id}")
 
_DB: dict[str, dict] = {"1": {"name": "Ada"}}
 
def fetch_row(user_id: str) -> dict:
    return _DB[user_id]
 
def get_user(user_id: str) -> dict:
    try:
        return fetch_row(user_id)
    except KeyError as exc:
        raise UserNotFoundError(user_id) from exc
 
def parse_id(raw: str) -> str:
    try:
        value = int(raw)
    except ValueError:
        raise ValueError(f"invalid id: {raw!r}") from None
    if value < 1:
        raise ValueError("id must be positive")
    return str(value)
 
try:
    get_user("999")
except UserNotFoundError as exc:
    print(exc)
    print(exc.__cause__)

What this demonstrates:

• from exc sets __cause__ for debugging chains
• from None hides parser internals from API consumers
• Domain exceptions carry identifiers for handlers and logs
• Bare validation raises still produce clear messages

Deep Dive

How It Works

• raise NewError() starts a new exception at current traceback point
• raise NewError() from exc links exc as __cause__
• Bare raise inside except re-raises the caught exception in-flight
• raise exc from stored variable can reset traceback context - prefer bare raise
• Exception.__context__ may differ from __cause__ when implicit chaining occurs

Chaining Choices

Gotchas

• Losing cause with raise New() without from - implicit context may still appear but is ambiguous. Fix: always use from exc when wrapping.
• Swallowing with from None everywhere - hides root causes in ops. Fix: reserve from None for user-input parsing boundaries.
• raise exc after except block ends - traceback points at reraise site. Fix: bare raise only inside active except.
• Chaining loops - A from B from A in recursive wrappers. Fix: raise domain error once at boundary.
• Logging exc_info then raising different type without from - logs and traceback disagree. Fix: chain or log inside handler that bare re-raises.

Alternatives

FAQs

Related

• Custom Exception Hierarchies - domain types
• Exceptions Basics - try/except structure
• Retries & Backoff - raise after retries
• Errors & Logging Best Practices - operational rules

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.