TypeError: metaclass conflict in Python Multiple Inheritance

Verified FixPython 3.10+Python Native OOPSilo: oop

Quick Fix / Solution Rapide

Create a unified metaclass that inherits from all parent metaclasses (class CombinedMeta(MetaA, MetaB): pass) and assign it to the child class.

Root Cause Analysis

This error occurs when Python attempts to construct a class via multiple inheritance whose parent classes derive from different, unrelated metaclasses, and neither metaclass is a subclass of the other.

1. The Metaclass Calculation Rule

In Python, when a class C(A, B) is defined, Python determines its metaclass by inspecting type(A) and type(B). If A has metaclass MetaA and B has metaclass MetaB, Python requires the metaclass of C to be a subclass of both MetaA and MetaB. If MetaA and MetaB are separate subclasses of type, Python raises TypeError: metaclass conflict: the metaclass of a derived class must be a non-strict subclass of the metaclasses of all its bases.

2. Combining ABCMeta with GUI Frameworks (PyQt / PySide / Tkinter)

A classic conflict occurs when combining abc.ABCMeta (from abc.ABC) with sip.wrappertype (from PyQt QObject).

3. Combining Enums with Custom Metaclasses

enum.EnumType has strict metaclass rules that reject standard multiple inheritance.

4. ORM Model Base Classes (Django / SQLAlchemy)

Django's ModelBase and SQLAlchemy's DeclarativeMeta cannot be mixed directly in a single child class without a composite metaclass.

Reproduction Code (MCVE)

Example: Bug Reproduction

# Simulating metaclass conflict between two unrelated metaclasses
class MetaA(type):
    pass

class MetaB(type):
    pass

class BaseA(metaclass=MetaA):
    pass

class BaseB(metaclass=MetaB):
    pass

# Multiple inheritance triggers TypeError: metaclass conflict
class Combined(BaseA, BaseB):
    pass

Solution 1: Define a Combined Composite Metaclass

Create a composite metaclass that inherits from both parent metaclasses, resolving the MRO conflict.

Example: Recommended Solution

class MetaA(type):
    pass

class MetaB(type):
    pass

# 1. Create unified composite metaclass
class CombinedMeta(MetaA, MetaB):
    pass

class BaseA(metaclass=MetaA):
    pass

class BaseB(metaclass=MetaB):
    pass

# 2. Explicitly assign composite metaclass
class Combined(BaseA, BaseB, metaclass=CombinedMeta):
    pass

instance = Combined()
print(f'Class created successfully with metaclass: {type(Combined).__name__}')

Solution 2: Use Composition Over Inheritance

Instead of multiple inheritance across conflicting framework classes, hold an instance of one class inside the other.

Example: Alternative Solution

class ComponentA:
    def do_action_a(self):
        return 'Action A'

class ServiceB:
    def __init__(self):
        self.component_a = ComponentA()
    def execute(self):
        return f'Service executing with {self.component_a.do_action_a()}'

print(ServiceB().execute())

A common mistake is trying to solve the conflict by simply setting metaclass=type. type is a superclass of MetaA and MetaB, not a subclass. Python requires a common subclass. Edge cases occur with abc.ABCMeta in PyQt: define class QABCMeta(type(QObject), abc.ABCMeta): pass. Contrast this error with TypeError: Cannot create a consistent method resolution order (MRO), which occurs when class inheritance graph contains cycles.

Previous Next