# sqlalchemy.orm.exc.UnmappedInstanceError：类 'builtins.dict' 未映射

- **ID:** `python/sqlalchemy-orm-session-merge-error`
- **领域:** python
- **类别:** runtime_error
- **验证级别:** ai_generated
- **修复率:** 80%

## 根因

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

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| 3.x | active | — | — |

## 解决方案

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

## 无效尝试

- **Converting dict to object manually without proper mapping.** — Object still not recognized by ORM. (80% 失败率)
- **Using session.add() with dict.** — Same error; session expects mapped instances. (90% 失败率)