Mastra 工作流重试机制与错误处理3 步实现零失败的完整指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra一次上游接口抖动就可能让整条 Mastra 工作流被标记失败。这篇文章带你配好工作流级别的重试机制讲清楚触发、间隔、终止三个环节怎么工作再用运行结果和日志验证重试真的生效最后给出 3 种重试没生效的排查路径。复盘一次工作流失败是怎么发生的凌晨 2 点值班同学被一条告警叫醒白天跑的 400 次抓取新闻 → 摘要 → 入库流程里37 次以 failed 结束。翻日志发现失败几乎都集中在第一步——上游接口偶尔返回 502这一步直接抛错后面两步压根没跑。这类失败的共同点错误是偶发的同一条数据 10 分钟后重跑大概率就成功了。但工作流不区分偶发和永久一步抛错整个 run 直接判死。手动重跑不现实400 次里人工挑出 37 次来恢复更不现实。所以你需要的是让失败的那一步自己再跑几次。Mastra 的重试机制干的就是这件事。拆解触发、间隔与终止三件事触发哪些错误会进入重试判定标准只有一个步骤的 execute 函数抛出了错误。只要抛出来执行引擎就把它送进重试循环。两个例外不会触发重试错误被步骤内部的 try/catch 吞掉步骤正常返回了数据——引擎看到的是一次成功不会重试抛出的是 MastraNonRetryableError。这个错误类型明确告诉引擎别再试了适合数据不存在、权限不足这类重试多少次都没用的场景。等待两次尝试之间隔多久工作流级别用 retryConfig.delay 统一指定单位毫秒固定间隔。delay 写 2000第 2 次尝试前要等 2 秒第 3 次、第 4 次也一样不是指数退避。这个间隔对整条工作流所有步骤共用不能按步骤单独调。终止重试什么时候停两种情况停下次数耗尽。总执行次数 1 次首发 attempts 次重试attempts 写 5 就是最多跑 6 遍全挂之后步骤标记为 failed工作流状态置为 failed结果里保留最后一次错误的完整信息。碰到不可重试错误立刻终止不浪费剩余次数。配置给工作流加一道保险最小可用配置 8 行工作流级别一次配好所有步骤共用export const myWorkflow createWorkflow({ retryConfig: { attempts: 5, // 首发之外最多重试 5 次 delay: 2000, // 每次重试前等 2 秒 }, }) .then(fetchStep) .commit()只有一个步骤不靠谱比如调第三方 API 的那个就在该步骤上加 retries: 3。步骤级配置会覆盖工作流级的 attempts但 delay 仍然走 retryConfig。参数细节可参考官方文档工作流错误处理。验证重试真的生效了吗配完别默认它生效了用三条证据确认看 run 结果。start 返回的 result 里steps 字段逐步记录每步的状态和错误失败步骤能看到最终抛出的错误成功步骤能看到输出。看实时流。用 run.stream() 跑一次chunk 里能看到步骤被重新执行的记录。配合一个故意失败 2 次再成功的 mock 接口是验证重试最快的办法。看可观测性。Mastra 的 tracing 给每个步骤记 span重试失败时会带上 status: failed 的错误信息部署上云之后运行记录和日志面板里能直接看到每次尝试的时间线这正是排查AI 工作流失败重试问题最直观的入口。排查重试没生效的 3 种常见原因现象步骤失败了但只执行了一次。原因通常是配置位置写错。retryConfig 必须挂在 createWorkflow 的参数里attempts 缺省为 0只写了 delay 等于没开重试。排查项确认 attempts ≥ 1且结构是 createWorkflow({ retryConfig: { attempts, delay } }) 而不是写在步骤对象上。现象错误明明抛了却直接 failed一次没重试。两种可能错误被步骤内部 catch 后当正常返回值处理了引擎根本没看到错误或者抛的是 MastraNonRetryableError。排查项把 execute 里的 catch 块去掉让错误原样往外冒再看重试是否出现。现象重试次数和等待时间与预期对不上。原因是把首发算进了 attemptsattempts 写 5 实际最多执行 6 次另外步骤上的 retries 会覆盖工作流级 attempts。排查项在步骤里加一行日志计数总耗时应等于执行次数 - 1× delay对不上就说明覆盖关系没理清楚。重试解决不了确定性错误它的价值是把偶发抖动挡在失败告警之外把 5 次尝试都解决不了的问题交给 onError 回调发通知、转人工处理。现在就做一件事挑出线上失败率最高的那个工作流加上 retryConfig写一个失败 2 次再成功的 mock 步骤跑一遍在结果里亲眼看到两次重执行记录再考虑上线。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考