How to Declare Custom Exceptions in Modern Python

By the end of this page, you will understand how to create custom exceptions in Python by subclassing Exception, passing error text to the base class correctly, and optionally storing extra context safely. You will also learn how args, __str__, and custom attributes work, and how to write exception classes that behave like built-in exceptions.

In Python, custom exceptions are usually created by subclassing Exception or one of its subclasses.

The key idea is this:

• An exception is just a class
• Raising an exception means creating an instance of that class
• Built-in exception behavior depends partly on the base class storing constructor values in args

A correct custom exception should usually do two things:

1. Inherit from Exception
2. Call Exception.__init__(...) with the message or values you want the exception to display

For example:

class MyError(Exception):
    pass

This is already a valid custom exception.

You can raise it like this:

raise MyError("Something went wrong")

Python stores the supplied values in exception.args. When the exception is printed, Python usually uses those values to build the string representation.

That is why calling the parent constructor matters.

Why message caused a warning

Think of an exception like a labeled emergency report.

• The exception class is the category of the report, like ValidationError or FileFormatError
• The message is the human-readable description of what went wrong
• The extra attributes are attached evidence, like a filename, record ID, or bad value

Built-in exceptions already know how to print the report summary because they store the main message in a standard place: args.

So when you create your own exception, the safest pattern is:

• put the printable message into the base Exception
• put any extra information into your own attributes

That way, Python and other tools can still print the error naturally, while your code can access more detailed context when needed.

Basic custom exception

class MyError(Exception):
    pass

raise MyError("Something went wrong")

This works because Exception already knows how to store the message in args.

Custom exception with extra data

class MyError(Exception):
    def __init__(self, message, payload=None):
        super(MyError, self).__init__(message)
        self.payload = payload

Usage:

try:
    raise MyError("Invalid input", payload={"field": "age", "value": -1})
except MyError as e:
    print(str(e))
    print(e.payload)

Consider this example:

class ValidationError(Exception):
    def __init__(self, field, value):
        message = "Invalid value for %s: %r" % (field, value)
        super(ValidationError, self).__init__(message)
        self.field = field
        self.value = value

try:
    raise ValidationError("age", -1)
except ValidationError as e:
    print("message:", str(e))
    print("args:", e.args)
    print("field:", e.field)
    print("value:", e.value)

What happens step by step

1. Python defines the class ValidationError.

2. raise ValidationError("age", -1) creates a new exception object.

3. Inside __init__, the code builds this message:

Custom exceptions are useful whenever your program needs to express specific failure types clearly.

Input validation

class ValidationError(Exception):
    pass

Used when a user enters invalid data in a form or API request.

File and configuration loading

class ConfigError(Exception):
    pass

Used when a config file is missing required keys or contains invalid values.

API clients

class ApiError(Exception):
    def __init__(self, message, status_code=None):
        super(ApiError, self).__init__(message)
        self.status_code = status_code

Useful when you want to store the HTTP status code along with the message.

Data processing pipelines

class RecordFormatError():
     ():
        (RecordFormatError, ).__init__(message)
        .record = record

In real projects, developers usually organize exceptions around domains and use them to support clear error handling.

Common pattern: base application exception

class AppError(Exception):
    pass

class ValidationError(AppError):
    pass

class DatabaseError(AppError):
    pass

This lets you catch all application-specific problems with one base class:

try:
    do_work()
except AppError as e:
    print("Application error:", e)

Pattern: add structured context

class ApiError(Exception):
    def __init__(self, message, status_code, response_body=None):
        super(ApiError, self).__init__(message)
        self.status_code = status_code
        self.response_body = response_body

1. Forgetting to call the base class constructor

Broken:

class MyError(Exception):
    def __init__(self, message):
        self.text = message

Problem:

• str(e) may not behave as expected
• args will not contain the message

Better:

class MyError(Exception):
    def __init__(self, message):
        super(MyError, self).__init__(message)
        self.text = message

2. Using message as a custom attribute in old Python versions

Problematic in Python 2.6:

class MyError(Exception):
    def __init__():
        .message = message

Custom exception patterns compared

Quick pattern

class MyError(Exception):
    def __init__(self, message, data=None):
        super(MyError, self).__init__(message)
        self.data = data

Raise it

raise MyError("Something went wrong", data={"id": 123})

Catch it

try:
    do_work()
except MyError as e:
    print(e)        # human-readable message
    print(e.args)   # standard exception arguments
    print(e.data)   # custom extra data

Rules to remember

• Inherit from Exception
• Pass the printable message to the base class
• Store extra context in your own attributes
• Avoid using self.message in old Python compatibility code
• Use simple subclasses when extra data is not needed

Should custom exceptions inherit from Exception or BaseException?

Use Exception. BaseException is meant for special built-in exceptions such as SystemExit and KeyboardInterrupt.

How do I include a message in a custom Python exception?

Pass the message to the parent constructor:

super(MyError, self).__init__(message)

This stores the text in args so it prints naturally.

Can a custom exception store extra data?

Yes. Add your own attributes such as code, filename, field, or payload.

Should I use self.message in a custom exception?

Avoid it, especially in Python 2.6 compatibility code, because .message had deprecated special behavior.

What is args on an exception?

• try and except — Needed to catch and handle exceptions.
• raise — Used to create and throw exceptions.
• Exception hierarchy — Helps you choose the right base class and organize related errors.
• __init__ methods — Important when adding custom attributes to exception objects.
• __str__ methods — Useful when customizing how an exception is displayed.
• Object-oriented programming in Python — Custom exceptions are classes, so class basics matter.
• Built-in exceptions — Understanding standard exceptions helps you design your own consistently.
• Guard clauses — Common pattern for raising exceptions early when input is invalid.