How Do You Create Custom Exceptions?

A custom exception is a class that inherits from Exception, or from a more specific built-in exception type.

class ValidationError(ValueError):
    def __init__(self, field, message):
        super().__init__(f"{field}: {message}")
        self.field = field
        self.message = message


try:
    raise ValidationError("email", "must contain @")
except ValidationError as err:
    print(err)                          # email: must contain @
    print(err.field)                    # email
    print(isinstance(err, ValueError))   # True

The class inherits from ValueError rather than Exception, and that is the important design decision. It means callers who already handle ValueError — which plenty of validation code does — will catch your error too, without knowing it exists. Deriving from a built-in exception is how you fit your error into an existing hierarchy rather than creating an island.

The custom __init__ builds a message that includes the field name, calls super().__init__ with it, and then stores the field and the raw message on the instance. Calling super().__init__ is what makes str(err) work, so the error reads properly in a traceback while still carrying structured data for programmatic use.

Two habits worth keeping. Store the structured data on the instance rather than only in the message, so callers can react to it without parsing strings. And keep the class small — an exception that carries data and nothing else is easy to test and easy to document.

You define a class that inherits from Exception. The body can be empty, because the only thing the class needs to do is identify the error type. The exception hierarchy is what makes catching useful — an except clause names a class, so the whole subtree below that class is caught.

The interesting decision is which base to inherit from. Exception is the safe default, since it is caught by except Exception and it excludes the control-flow exceptions KeyboardInterrupt and SystemExit. But inheriting from a more specific built-in is often better: a validation error that subclasses ValueError is caught by code already handling ValueError, and a missing-record error that subclasses LookupError behaves like the built-in KeyError.

Three conventions make a custom exception well behaved. Give it a docstring saying when it is raised. Keep the constructor simple, ideally accepting a message plus structured data and calling super().__init__ with the formatted message. And do not add a lot of behaviour to the exception — it is a data carrier, and the handling logic belongs at the call site.

Two more things to know. Python has no checked exceptions, so nothing forces a caller to handle your error — you rely on documentation and on deriving from a sensible base. And the ExceptionGroup class, available from 3.11, lets you raise a group of exceptions at once when several validations fail at the same time.

A small hierarchy with a shared base lets callers handle a whole family of errors with one clause while still being able to catch the specific one.

class AppError(Exception):
    """Base class for every error this package raises."""


class NotFoundError(AppError):
    def __init__(self, resource, identifier):
        super().__init__(f"{resource} {identifier} not found")
        self.resource = resource
        self.identifier = identifier


class ConfigError(AppError):
    pass


def load(records, resource, identifier):
    for record in records:
        if record["id"] == identifier:
            return record
    raise NotFoundError(resource, identifier)


try:
    load([{"id": 1}], "user", 7)
except AppError as err:
    print(type(err).__name__, "->", err)
    print(isinstance(err, AppError))

The output is NotFoundError -> user 7 not found, followed by True. The except AppError clause caught the specific NotFoundError because it inherits from AppError, and the type name and the attributes are both available to the handler.

This shape is what you want in a library. The base class gives the caller a single place to catch everything the package can raise, while the subclasses let a caller who cares about one specific failure catch only that one. The alternative — a flat set of unrelated exception classes — forces callers to enumerate every one of them, and any new exception they have never heard of would escape their handler entirely.

Two details. The structured attributes matter: resource and identifier are available on the instance, so a handler can build an HTTP response without parsing the message string. And the base class carries a docstring, which is how a reader discovers the whole family at once.