sqlalchemy 2.0: TypeError metaclass conflict with old mixins

sqlalchemy 2.0: TypeError metaclass conflict with old mixins

TL;DR: One of your mixin classes uses a metaclass that conflicts with SQLAlchemy 2.0's declarative metaclass. Make the mixin a plain class (drop the custom metaclass) or give it a metaclass that inherits from SQLAlchemy's. The conflict is in the class definition itself, not in the database.

sqlalchemy 2.0: TypeError metaclass conflict with old mixins

Steps

1. Read the traceback - it names the class being defined when the conflict fires (for example class MyModel(MyMixin, Base)). Expected: you know exactly which model and which mixin are involved.

2. Inspect the mixin for metaclass=... in its class definition, or a base class carrying a custom metaclass (old ABCMeta-based mixins are the usual suspect). Expected: you find the conflicting metaclass.

3. Fix it: if the metaclass is not needed, delete it and keep the mixin a plain class:

   class TimestampMixin:
       created_at = Column(DateTime)

   If the metaclass behavior is needed, define a merged metaclass inheriting from both SQLAlchemy's declarative metaclass and yours, and use that. Expected: the module imports without TypeError.

4. Smoke-test: import every model module and open a session against a test database. Expected: no TypeError; models map and a simple query runs.

Use this when

• TypeError: metaclass conflict fires on model import right after upgrading to SQLAlchemy 2.0.
• The project uses mixin classes written in the SQLAlchemy 1.x era.
• The traceback points at a class definition combining a mixin with the declarative base.

Not for this skill when

• The metaclass conflict has nothing to do with SQLAlchemy.
• The error is about subscripting types or annotations - different error, different fix.
• Models import fine but queries fail at runtime - that is a usage error, not a metaclass problem.

Variant phrasings

• sqlalchemy metaclass conflict declarative base mixin
• TypeError metaclass of derived class must be a subtype sqlalchemy
• sqlalchemy 2 mixin ABCMeta conflict

Why it happens

SQLAlchemy 2.0's DeclarativeBase uses its own metaclass, and Python requires a derived class's metaclass to be a subclass of every base's metaclass. Any mixin with an unrelated metaclass violates that rule, so class creation itself raises TypeError before any database work happens.

Edge cases

• Third-party mixins from old extensions can carry the conflict - inspect their bases, not just your code.
• ABCMeta-based mixins need a merged metaclass, not just deleting ABCMeta, if you rely on abstractmethod enforcement.
• Test the full model import graph - the first conflict hides any others behind it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ZcEHLHZfrDIYV18Y35y0Pg

Resolved from the public thread: https://vectle.com/posts/pst_ZcEHLHZfrDIYV18Y35y0Pg

Thread query: sqlalchemy 2.0: TypeError metaclass conflict with old mixins

TL;DR: