How to Resolve Python Error "TypeError: exceptions must derive from BaseException"

The TypeError: exceptions must derive from BaseException is a fundamental error in Python's exception handling mechanism. It occurs when you use the raise statement with something that is not a valid exception object – specifically, something that doesn't inherit (directly or indirectly) from the built-in BaseException class. Typically, this happens when trying to raise a simple string or another non-exception type.

This guide explains Python's exception hierarchy and shows the correct ways to raise built-in or custom exceptions.

Understanding the Error: Python's Exception Hierarchy

Python has a well-defined hierarchy for exceptions, designed for structured error handling. At the very top of this hierarchy sits the BaseException class. All built-in exceptions, and crucially, all exceptions that are meant to be caught and handled within typical program flow, inherit from this base class.

The raise statement is specifically designed to work with instances of classes that fit into this hierarchy. When you raise something, Python expects it to be an object representing an error condition, derived from BaseException.

The Cause: Raising Non-Exception Objects

This TypeError occurs because the object you provided to the raise statement is not an instance of BaseException or one of its subclasses. The most common mistake is trying to raise a simple string.

# Error Scenario: Raising a string
user_input = "some text"

try:
    if not user_input.isdigit():
        # ⛔️ TypeError: exceptions must derive from BaseException
        # can not raise a plain string literal
        raise "Input must be numeric!"
except TypeError as e:
    print(e)

# Error Scenario: Raising another non-exception type (e.g., integer)
try:
    error_code = 404
    # ⛔️ TypeError: exceptions must derive from BaseException
    raise error_code
except TypeError as e:
    print(f"Error raising int: {e}")

note

Strings, integers, lists, etc., do not inherit from BaseException and therefore can not be used directly with the raise statement.

Solution 1: Raise Instances of Built-in Exceptions (Recommended)

Python provides a rich set of built-in exception classes for common error scenarios (ValueError, TypeError, KeyError, FileNotFoundError, IndexError, etc.). The correct way to raise an error is to create an instance of one of these classes, usually passing an informative message to its constructor.

# ✅ Corrected Code: Raising a built-in exception instance
user_input = "some text"
expected_type = int

if not isinstance(user_input, expected_type):
    # Create an instance of TypeError with a message
    error_message = f"Input must be of type {expected_type.__name__}, got {type(user_input).__name__}"
    raise TypeError(error_message) # Raise the TypeError instance

# Example with ValueError
user_age = -5
if user_age < 0:
     # Create an instance of ValueError
    raise ValueError("Age can not be negative.")

Output:

ERROR!
Traceback (most recent call last):
  File "<main.py>", line 8, in <module>
TypeError: Input must be of type int, got str

• You instantiate the exception class (e.g., ValueError(...), TypeError(...)) and raise that instance.
• Consult the Python documentation for built-in exceptions to choose the most semantically appropriate one for your error condition.

Solution 2: Define and Raise Custom Exceptions

For application-specific errors, it's good practice to define your own exception classes. Custom exceptions must inherit from Exception (which itself inherits from BaseException).

# ✅ Define a custom exception class inheriting from Exception
class InvalidUserInputError(Exception):
    """Custom exception for invalid user input scenarios."""
    # You can add custom methods or attributes here if needed
    pass # Basic custom exception needs only 'pass'

# Example usage
user_email = "not-an-email"

if "@" not in user_email:
    # Raise an instance of the custom exception
    raise InvalidUserInputError(f"Invalid email format provided: {user_email}")

# --- More detailed custom exception ---
class NegativeValueError(Exception):
    def __init__(self, value, message="Value can not be negative"):
        self.value = value
        self.message = message
        # Call the base Exception __init__ with the message
        super().__init__(self.message)

    def __str__(self):
        # Custom string representation
        return f"{self.message} (value was: {self.value})"

# Raising the detailed custom exception
score = -10
if score < 0:
    raise NegativeValueError(score)

Output

ERROR!
Traceback (most recent call last):
  File "<main.py>", line 12, in <module>
InvalidUserInputError: Invalid email format provided: not-an-email

• Always inherit from Exception for standard application errors.
• Custom exceptions make your error handling more specific and readable (e.g., except InvalidUserInputError:).

Important Distinction: BaseException vs. Exception

While the error message mentions BaseException, you should almost always inherit your custom exceptions from Exception, not directly from BaseException.

• BaseException: The ultimate base class. It includes exceptions that are generally not meant to be caught by typical application code, such as SystemExit (raised by sys.exit()) and KeyboardInterrupt (raised when the user presses Ctrl+C). Catching BaseException can mask these critical exit signals.
• Exception: Inherits from BaseException. This is the base class for virtually all built-in, non-system-exiting exceptions (ValueError, TypeError, etc.). Your custom exceptions should inherit from Exception so that standard except Exception: blocks can catch them if necessary, while still allowing system exits to propagate.

Handling Raised Exceptions (try...except)

Remember that if an exception is raised and not handled by an appropriate except block, your program will terminate and print a traceback.

def check_value(val):
    if val < 0:
        raise ValueError("Value must be non-negative.")
    return val * 2

try:
    result = check_value(-5) # This will raise ValueError
    print(f"Result: {result}")
except ValueError as e:
    # ✅ Catch the specific error
    print(f"Caught expected error: {e}") # Output: Value must be non-negative.
except Exception as e:
    # Optional: Catch any other standard exception
    print(f"Caught unexpected standard error: {e}")

print("Program continues after handling.")

Output:

ERROR!
Caught expected error: Value must be non-negative.
Program continues after handling.

Handling exceptions allows your program to recover from errors or log them gracefully instead of crashing.

Conclusion

The TypeError: exceptions must derive from BaseException signals that you attempted to raise an object that is not part of Python's exception hierarchy (most often a plain string).

To fix this:

1. Raise instances of appropriate built-in exception classes (inheriting from Exception, like ValueError, TypeError, RuntimeError, etc.): raise ValueError("An informative message").
2. Define custom exception classes for application-specific errors, ensuring they inherit from Exception: class MyCustomError(Exception): pass, then raise MyCustomError("Details").

Never raise raw strings, numbers, or other non-exception types. Always use objects instantiated from classes derived from Exception.