python runtime_error ai_generated true

sqlalchemy.orm.exc.UnmappedInstanceError: Class 'builtins.dict' is not mapped

ID: python/sqlalchemy-orm-session-merge-error

Also available as: JSON · Markdown · 中文
80%Fix Rate
85%Confidence
0Evidence
2025-10-05First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
3.x active — — —

Root Cause

Passing a dictionary instead of a mapped class instance to session.merge().

generic

中文

向 session.merge() 传递字典而不是映射类实例。

Workarounds

  1. 95% success Create mapped instance from dict. 
    user_data = {'id': 1, 'name': 'Alice'}
user = User(**user_data)
merged_user = session.merge(user)
  2. 90% success Use session.execute() with insert statement. 
    from sqlalchemy import insert
stmt = insert(User).values(**user_data)
session.execute(stmt)

Dead Ends

Common approaches that don't work:

  1. Converting dict to object manually without proper mapping. 80% fail

    Object still not recognized by ORM.

  2. Using session.add() with dict. 90% fail

    Same error; session expects mapped instances.