FastAPI添加async后报'coroutine' object is not iterable错误

该错误和Swagger UI无关，本质是async def定义的接口执行完成后，返回给FastAPI的响应内容中包含了未被await的协程对象。FastAPI在序列化响应阶段调用jsonable_encoder尝试将返回值转为JSON兼容格式时，会尝试遍历对象、读取对象属性，而协程对象本身不可迭代、也没有可序列化的__dict__属性，就会抛出你看到的两个关联TypeError。

你提到的去掉async后接口正常的现象也符合这个逻辑：去掉async后函数内无法使用await语法，所有调用都是同步执行、直接返回实际结果，不存在未执行的协程对象，自然不会触发序列化错误。另外你要执行的contents = await job_image.read()本身是合法操作，只要在async接口内正确await就不会触发问题，报错和读取上传文件的逻辑无关。

典型错误写法（漏写await返回协程）：

# 异步的数据库创建方法
async def create_job(db, data):
    # 省略异步ORM操作逻辑
    return new_job

@router.post("/create")
async def job_create_post_view(...):
    # 省略参数解析、文件读取逻辑
    # 错误：异步方法漏写await，new_job是未执行的协程对象
    new_job = create_job(db, form_data)
    return {"code": 0, "data": new_job}

修复后写法：

@router.post("/create")
async def job_create_post_view(...):
    # 省略参数解析、文件读取逻辑
    # 正确：加await拿到实际执行结果
    new_job = await create_job(db, form_data)
    return {"code": 0, "data": new_job}

• 全量检查接口所有返回分支：所有异步函数的调用必须前置await关键字。90%以上的该类报错都是异步CRUD、异步工具函数调用时漏写await，直接把未执行的协程塞进了返回结构，触发序列化失败。
• 检查所有Depends注入的依赖：包括is_htmx、get_db在内的所有依赖，如果是async def定义的，要确认依赖内部所有异步调用都正确加了await，不要让依赖的返回值是协程对象。
• 检查手动构造响应的逻辑：如果你在接口内手动调用jsonable_encoder、直接返回JSONResponse/HTMLResponse等响应对象，要确认传入的内容都是实际执行结果，不是未await的协程。
• 数据库适配注意：如果你用的是同步版SQLAlchemy的同步Session，在async接口中调用同步数据库操作不会触发当前这个序列化错误，但会阻塞异步事件循环，影响服务性能。这种场景要么把接口改成普通def，让FastAPI自动把接口逻辑放到线程池执行避免阻塞，要么改用异步版SQLAlchemy的AsyncSession适配异步接口写法。

内容的提问来源于stack exchange，提问作者Julie An