企业官网建设流程全解析

Mastra 工作流重试机制与错误处理实战：retries 怎么配、不生效怎么查

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

Mastra 工作流里，一个步骤调用外部 API 偶尔返回 500 或超时，是整条流程重跑，还是只补跑失败的那一步？Mastra 内置的重试机制给出的答案是：步骤级失败会按配置次数自动重试，已跑完的步骤输出不会丢，而你不想重试的错误可以显式标记为不可重试。本文讲清楚重试策略配置、错误分类，以及重试没生效时怎么排查。

步骤偶发失败：整条流程重跑还是只补跑失败步骤？

整条工作流重跑代价不小：前面步骤已经写过的数据、调用过的接口要再执行一遍，副作用无法忽略。Mastra 的做法是步骤粒度重试——当某个叶子步骤执行失败，引擎只为它重新发布一次workflow.step.run事件，事件里带着stepResults（此前所有步骤的输出）和递增后的retryCount。也就是说，重试是"补跑失败步骤"，不是"重放整条流程"，这是理解后面所有配置的前提。

Mastra 重试策略配置：retries 参数写在哪

重试参数有两个位置：

1. 步骤级retries：写在createStep的定义里，只对这个步骤生效；
2. 工作流级retryConfig.attempts：写在createWorkflow里，作为所有步骤的默认值。

生效优先级是步骤级覆盖工作流级，两者都没配时默认 0，即失败即终止、不重试。这里有个容易踩的坑：retries表示"重试次数"而不是"总执行次数"，retries: 3意味着该步骤最多执行 4 次（1 次原始 + 3 次重试）。

import { createStep, createWorkflow } from '@mastra/core/workflows'; const callApi = createStep({ id: 'call-api', retries: 3, inputSchema: z.object({ url: z.string() }), outputSchema: z.object({ data: z.any() }), execute: async ({ inputData }) => fetchJson(inputData.url), }); const flow = createWorkflow({ id: 'report-flow', retryConfig: { attempts: 2 }, steps: [callApi] });

想要指数退避？用上下文里的 retryCount 自己算延迟

核心重试循环没有内置延迟：上一次失败后，下一次重试会立即发起。如果需要工作流指数退避这类策略（比如等限流窗口过去再试），可以用execute上下文里的retryCount自己控制：

execute: async ({ inputData, retryCount }) => { if (retryCount > 0) { await sleep(Math.pow(2, retryCount) * 1000); // 2s → 4s → 8s } return fetchJson(inputData.url); }

固定间隔就把这一行换成常量延迟即可。退避逻辑写在步骤内部，好处是它和重试计数天然对齐，不用额外状态。

错误类型识别：用 MastraNonRetryableError 划清可重试边界

重试不是越多越好。对参数校验失败、业务规则不满足这类永久性错误，重试 3 次也是浪费。Mastra 提供了MastraNonRetryableError：步骤里抛出它，该步骤的执行结果会被打上nonRetryable标记，引擎不会再重试。适合"重试也没用"的场景，比如无效的模板 ID、鉴权失败。

而网络超时、429 限流、5xx 这类瞬时错误，抛普通错误即可，由引擎按retries配置处理。需要结构化分类时，MastraError还带 domain / category 字段，方便在监控端按错误类型聚合。

Mastra 错误追踪：从 stepResults 和追踪视图看到每一次重试

stepResults 里看每一步的状态与错误

运行结束后，stepResults中每个步骤都有status和error字段，失败结果上还能看到nonRetryable标记。每一次重试对应一组workflow.step.run/workflow.step.end的 pubsub 事件，想接自定义告警（比如重试耗尽时发通知），订阅这些事件就够了。

接入 observability 后在追踪视图里定位失败

接入@mastra/observability后，每次工作流运行会生成 trace，每个步骤的执行是其中的 span，重试过程在追踪视图里逐次可见，失败步骤的异常信息直接挂在对应 span 上。仓库的 observability/ 目录 下有 mastra、langfuse 等多个 provider 实现可按需选择。

重试没生效怎么排查：三种不重试的判定

引擎的停止条件就一条：retryCount >= retries，或结果被标记nonRetryable。对照排查，通常是这三种情况：

1. 根本没配重试——步骤级retries和工作流级retryConfig都为空，默认就是 0 次重试；
2. 抛了不可重试错误——步骤内部抛出了MastraNonRetryableError，重试被强制跳过；
3. 次数口径误解——retries: 3是重试 3 次、共执行 4 次，第 4 次失败属于预期内，不是"没重试"。

排查顺序建议：先在运行详情或追踪视图里数该步骤实际执行了几次，再确认错误是否带nonRetryable标记，最后核对配置是否写在了正确的工作流对象上。

高频问题

问：重试会从头重跑整条工作流吗？

不会。只有失败的步骤被重新发布执行，之前步骤的输出通过stepResults原样传入，失败步骤拿到的输入仍然是上游输出，不会二次触发。

问：配了 retries 但第一次失败就停了，先查什么？

按顺序查三处：抛出的错误是不是MastraNonRetryableError（会强制不重试）；这个retries是否写在支持重试的条目上（step、agent、tool 条目支持，mapping 条目不支持）；工作流级retryConfig是不是配到了另一个 workflow 上。

延伸阅读：步骤定义与 retries 字段、MastraNonRetryableError 定义。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra