Mastra 冒烟测试常见错误与排障指南Trace 丢失、部署失败到升级策略的完整修复手册【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文基于 Mastra 仓库中 mastra-smoke-test 技能排障文档 展开。该文档是 Mastra 冒烟测试Smoke Test体系中的第一响应手册覆盖本地开发与云端staging/production部署中最常见的故障场景——Trace 不出现、部署挂起、认证失败等。读完本文你将掌握一套可复制的诊断路径按症状定位根因、执行最小修复命令、并在问题无法解决时准确判断是否应该升级给平台团队。一、这份排障手册在 Mastra 冒烟测试体系中的定位在 Mastra 仓库中冒烟测试由 mastra-smoke-test SKILL 组织它定义了一张 12 项的强制测试清单覆盖 Setup、Agents、Tools、Workflows、Traces、Scorers、Memory、MCP、Errors、Experiments、Studio Deploy 与 Server Deploy。其中 Setup 与 Errors 在所有环境下都必须执行Traces、Studio/Server 部署则是云端环境的核心验证项。common-errors.md 就是这套测试体系的快速排障手册它把最常踩的坑浓缩为三张表Trace 问题、部署问题、升级标准。与它配套的还有cloud-deploy.mdstaging/production 部署全流程traces 测试参考Trace 采集与查询的完整协议server 测试参考Server 部署验证步骤gcp-debugging.md需要 GCP 权限时的底层调试入口。排查时遵循的总体原则是先按症状表对号入座执行最小修复命令若修复无效再进入升级流程。下面按这三个层次展开。二、Trace 不出现的三类典型症状Trace可观测性追踪是冒烟测试验证完整链路是否打通的关键证据。测试中一个最经典的场景是在 Studio 的/observability页面先确认 Studio 自身的操作产生 Trace再对已部署的 Server 发起一次 API 调用回到页面确认 Server 产生的 Trace 也出现。如果只见其一链路就有问题。症状一Server traces 缺失但 Studio traces 正常这是最常见的现象说明 Studio 与 Server 两条 Trace 上报链路中Server 一侧的认证凭据失效。文档给出的快速修复是症状可能原因快速修复Server traces 缺失Studio traces 正常Server 上的 token 过期/陈旧重新部署 Serverpnpx mastralatest server deploy -y为什么 Studio 正常而 Server 异常从 cloud-deploy.md 的排查细节可以推断Server 部署时平台会注入MASTRA_CLOUD_ACCESS_TOKEN一个用于 Trace 认证的 JWT若该 token 失效或未正确配置Server 的 trace 上报就会被拒。文档明确列出三个典型信号mobs-collector日志返回POST 200trace 已正常接收返回POST 401JWT 认证失败返回POST 404上报端点错误。若日志中出现401 invalid signature通常是JWT_SECRET 在服务之间不一致若部署日志出现mastra-cloud-observability-exporter disabled则说明平台 API 侧未配置JWT_SECRETServer 拿不到MASTRA_CLOUD_ACCESS_TOKEN。症状二完全没有 trace症状可能原因快速修复完全没有 trace部署时出现可观测性相关警告检查部署日志中是否出现MASTRA_CLOUD_ACCESS_TOKEN警告修复的第一步是回看部署输出。在 server 测试参考 中明确了两条必须记录的关键警告mastra-cloud-observability-exporter disabled—— 表示 trace 不会工作CLOUD_EXPORTER_FAILED_TO_BATCH_UPLOAD_LOGS—— 表示 trace 上报端点存在问题。在本地环境完全没有 trace 通常是另一类原因。根据 local-setup.md本地 trace 默认存储在内存中由MastraStorageExporter提供dev server 重启即丢失。排查本地 trace 缺失按以下顺序检查src/mastra/index.ts中Mastra实例是否配置了可观测性telemetry/observability配置重启 dev server配置变更需要重启生效检查浏览器控制台是否有 OTel 导出错误确认依赖中安装了mastra/observability。当前create-mastra脚手架默认的写法是PinoLoggerObservability含MastraStorageExporter、MastraPlatformExporter、SensitiveDataFilter并使用MastraCompositeStore将默认的 LibSQL 存储与承载observability域的 DuckDB 存储组合起来完整示例可参考 local-setup.md。症状三Studio 日志出现 Session expired症状可能原因快速修复Studio 日志出现 Session expired已知的 cookie 域名问题在 Studio 中重新认证在 cloud-deploy.md 中这一现象被归因于cookie 域名不匹配cookie domain mismatchStudio 需要定期重新认证。它通常与 OAuth 登录后的组织/账号切换问题并存浏览器可能默认登录到错误的账号或组织因此认证后务必校验当前身份cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId}深挖底层Trace 认证与 token 生命周期要真正理解以上症状需要了解云端 Trace 的认证模型。登录后凭据存放在~/.mastra/credentials.json包含token5 分钟过期的访问令牌、refreshToken长效刷新令牌以及user、organizationId等信息。traces 测试参考 提供了get_valid_token辅助函数完整实现了先验证 → 过期则用 refreshToken 刷新 → 刷新失败才重新登录的流程并会把新 token 回写回凭据文件get_valid_token() { local PLATFORM_URL${1:-https://platform.mastra.ai} local TOKEN$(jq -r .token ~/.mastra/credentials.json) local ORG_ID$(jq -r .currentOrgId // .organizationId ~/.mastra/credentials.json) # 先尝试当前 token local VERIFY$(curl -s $PLATFORM_URL/v1/auth/verify \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID) if echo $VERIFY | jq -e .user /dev/null 21; then echo $TOKEN return 0 fi # token 已过期——尝试刷新 local REFRESH_TOKEN$(jq -r .refreshToken ~/.mastra/credentials.json) if [ -z $REFRESH_TOKEN ] || [ $REFRESH_TOKEN null ]; then echo No refresh token. Re-login required. 2 return 1 fi local REFRESH_RESULT$(curl -s $PLATFORM_URL/v1/auth/refresh-token \ -X POST \ -H Content-Type: application/json \ -d {\refreshToken\: \$REFRESH_TOKEN\}) if echo $REFRESH_RESULT | jq -e .accessToken /dev/null 21; then local NEW_TOKEN$(echo $REFRESH_RESULT | jq -r .accessToken) local NEW_REFRESH$(echo $REFRESH_RESULT | jq -r .refreshToken) jq --arg t $NEW_TOKEN --arg r $NEW_REFRESH \ .token $t | .refreshToken $r \ ~/.mastra/credentials.json ~/.mastra/credentials.json.tmp \ mv ~/.mastra/credentials.json.tmp ~/.mastra/credentials.json echo $NEW_TOKEN return 0 fi echo Refresh failed. Re-login required. 2 return 1 }重要实践遇到401时不要急着重新登录登录会打开浏览器 OAuth 流程先用verifyrefresh-token接口尝试无感续期。只有当刷新失败时才执行pnpx mastralatest auth login并且在触发登录前务必提醒用户——因为它会弹出浏览器。直接查询 Trace 接口绕过 UI 验证链路当 UI 上迟迟不显示 trace但又需要确认采集链路本身是否工作可以绕过 Studio 直接查询 trace 接口。本地环境无需认证# 列出最近的 spans响应结构为 { pagination, spans } curl -s http://localhost:4111/api/observability/traces?page0perPage20 | jq . # 快速判定总数 0 且包含预期的 spanType curl -s http://localhost:4111/api/observability/traces?page0perPage100 | \ jq {total: .pagination.total, byType: ([.spans[].spanType] | group_by(.) | map({t: .[0], n: length}))}注意响应形状返回的是{ pagination: { total, page, perPage, hasMore }, spans: [...] }不是裸数组也没有traces键。每条 span 含spanTypeagent_run、tool_call、workflow_run、scorer_run、traceId、时间戳与 payload。云端则需要项目信息与有效 token使用上面的get_valid_tokenPROJECT_ID$(jq -r .projectId .mastra-project.json) # 或 .mastra-project-staging.json ORG_ID$(jq -r .organizationId .mastra-project.json) TOKEN$(get_valid_token https://platform.mastra.ai) curl -s https://mobs-query-vgvrl5lbxq-uc.a.run.app/api/observability/traces?page0perPage10resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .云端响应中几个关键字段metadata.buildId标识 trace 来自 studio 还是 server 的部署、requestContextStudio 触发的 trace 带有认证用户上下文Server 直调的 trace 为 null、statussuccess/error/running。可以用resourceId、runId、startedAtURL 编码的 JSON做过滤。三、部署问题排查部署挂起或超时症状可能原因快速修复部署挂起/超时网络或平台侧问题到平台项目仪表盘projects.mastra.ai确认部署是否实际成功然后重试这是一个先确认结果、再决定动作的场景CLI 超时并不一定代表部署失败平台侧可能已经完成了构建与发布。因此先到仪表盘核对状态再决定是否重试可以避免重复部署造成资源浪费。Cannot determine project name症状可能原因快速修复Cannot determine project name缺少 package.json在项目根目录存在合法 package.json下执行部署命令部署命令依赖项目根目录的package.json推导项目名。若在错误目录执行、或目录缺少 package.jsonCLI 无法确定项目身份就会报此错误。部署命令与多环境配置冒烟测试支持用一个项目同时面向本地、staging、production 三个环境通过独立的配置文件区分详见 SKILL.md 与 cloud-deploy.md环境配置文件平台 API URL部署 URLProduction.mastra-project.jsonhttps://platform.mastra.aiproject.studio.mastra.cloudStaging.mastra-project-staging.jsonhttps://platform.staging.mastra.aiproject.studio.staging.mastra.cloud每个环境拥有独立的 project ID互不干扰。部署前先设置目标环境# production export MASTRA_PLATFORM_API_URLhttps://platform.mastra.ai # staging export MASTRA_PLATFORM_API_URLhttps://platform.staging.mastra.ai部署 Studio 与 Server# Production默认使用 .mastra-project.json pnpx mastralatest studio deploy -y pnpx mastralatest server deploy -y # Staging显式指定配置文件 pnpx mastralatest studio deploy --config .mastra-project-staging.json -y pnpx mastralatest server deploy --config .mastra-project-staging.json -y-y标志用于自动确认设置。部署完成后从输出中记录 URL然后做健康检查# Staging curl https://project.server.staging.mastra.cloud/health # Production curl https://project.server.mastra.cloud/health # 预期响应{success:true}认证失效导致的部署失败若部署时出现 auth 错误文档给出的标准修复是登出后重新登录再重试pnpx mastralatest auth logout pnpx mastralatest auth login # 会打开浏览器 OAuth执行前先提醒用户部署相关的两个高频伪错误在 cloud-deploy.md 中记录了另外两个与部署相关的常见问题自定义路由静默失效自定义路由必须放在apiRoutes而不是routes字段中否则路由静默不注册且没有任何报错server: { apiRoutes: [helloRoute], // ✅ 正确 // routes: [helloRoute], // ❌ 错误——静默失败 }CORS 错误Server 部署通过SERVER_WRAPPER注入 CORS 配置。遇到 CORS 错误时先检查部署上的MASTRA_CORS_ORIGIN环境变量是否正确并确认来源域名与 Studio 域名模式匹配。四、Server API 验证与 Trace 链路校验部署完成后冒烟测试的 Server 验证遵循健康检查 → Agent API → 脚本化测试 → 回 Studio 看 trace的固定顺序。仓库提供了现成的验证脚本 test-server.sh.claude/skills/mastra-smoke-test/scripts/test-server.sh server-url [agent-id] [message] # 示例 .claude/skills/mastra-smoke-test/scripts/test-server.sh https://my-app.server.staging.mastra.cloud .claude/skills/mastra-smoke-test/scripts/test-server.sh https://my-app.server.mastra.cloud weather-agent Weather in Tokyo?该脚本依次执行检查依赖curl、jq→ 检查/health端点 → 调用 Agent 的/generate端点使用jq构造 JSON 以避免消息中的特殊字符问题→ 解析并展示响应 → 任一环节失败即退出并返回非零状态码。它的默认参数是 agent 为weather-agent、消息为What is the weather in Paris?与你用create-mastra脚手架生成的项目开箱即用。也可以直接 curl 验证核心端点server 测试参考 中的端点清单端点方法用途/healthGET健康检查/api/agents/id/generatePOSTAgent 生成/api/agents/id/streamPOST流式生成/custom-routeANY自定义 API 路由curl -X POST server-url/api/agents/weather-agent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:Weather in Tokyo?}]}最后一步是关键回到 Studio 的/observability页面并刷新确认 Server API 调用产生的 trace 出现。区分来源的方式是来源如何产生如何识别Studio tracesStudio UI 交互聊天、工具运行从 Studio 域名发起Server traces直接调用已部署 Server 的 API从 Server 域名发起如果只有 Studio traces说明 Server 的 trace 上报链路有问题参见上一章的 token 排查。另需注意 Server 冷启动可能耗时 1030 秒首次请求可能较慢trace 最多可能延迟约 30 秒出现排查前先留出等待窗口。五、何时升级到平台团队排障手册明确了快速修复无效时的升级标准。当出现以下任一情况应当联系平台团队而不是继续在应用层反复尝试重新部署无法修复 trace 问题部署日志中出现401或404错误问题跨多个项目持续存在。第一条表明问题不在单个部署实例的凭据而在更上层的配置第二条中的401认证失败与404端点错误往往对应平台侧服务的 JWT 配置或端点路由问题见第二章的mobs-collector日志解读第三条则说明问题具有系统性质而非特定项目的数据或配置问题。当排障需要进入基础设施层面例如查看mobs-collector日志、核对JWT_SECRET配置时需要GCP Console 访问权限。完整的内部基础设施调试指南见 gcp-debugging.md其中明确了什么时候该查 GCP 日志Server traces 不出现、部署静默失败、认证/会话问题。若你没有 GCP 权限应当联系具有基础设施访问权限的团队成员协助。六、附错误处理测试的断言基线common-errors.md将部署日志中的401/404列为升级信号而Errors测试errors.md则给出了应用层各错误场景的预期 HTTP 状态码基线二者互为补充——前者判断平台健康度后者验证应用自身的错误映射质量场景HTTP响应体形态未知 agent id404{ error: Agent with id id not found }或类似未知 tool id404{ error: Tool not found }未知 workflow id404{ error: Workflow not found }Workflow 缺少必填输入500{ error: Invalid input data: field expected ... }Tool 缺少必填输入200{ error: true, validationErrors: { ... } }JSON 体非法400{ error: ... }Hono body 解析失败文档特别标注了两处已知的不一致/潜在缺陷可作为回归监测点Tool 无效输入返回200且 body 中带error: true与 workflow/agent 的 HTTP 语义不一致Workflow schema 校验失败返回500属于潜在的服务端/API 错误映射 bug——客户端输入导致的校验失败按惯例应映射为 4xx。无论哪种场景通过标准都是每个错误响应都包含可读的error字段tool 用validationErrors、响应体中不泄露堆栈信息、HTTP 状态码与上表一致或存在已记录的偏差。七、附环境变量与快速命令速查排障过程中最容易搞混的是哪些变量该自己设、哪些平台会自动注入。根据 environment-variables.md需要手动设置的变量变量用途设置时机MASTRA_PLATFORM_API_URL指定目标是 staging 还是 production在mastra auth login之前OPENAI_API_KEYLLM API 访问运行 agents 之前ANTHROPIC_API_KEY备选 LLM若使用 Anthropic平台部署时自动注入、无需手动设置的变量MASTRA_CLOUD_ACCESS_TOKEN—— 用于 trace 认证的 JWTMASTRA_CLOUD_TRACES_ENDPOINT—— trace 上报端点。常用检查命令# 确认目标环境 echo $MASTRA_PLATFORM_API_URL # 确认登录状态 mastra auth status # 确认凭据身份 cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId} # 本地确认 :4111 上没有残留的 dev server端口被占用会静默换到 4112导致 curl 打错项目 lsof -i :4111最后一条值得单独强调mastra dev在:4111被占用时会自动递增端口如果没察觉后续 curl 都会命中之前测试会话残留的旧项目产生错误不在你怀疑的地方的假象。按 local-setup.md 的建议先清理端口再启动并用curl -s -o /dev/null -w HTTP %{http_code}\n http://localhost:4111/api/agents预期 200确认 dev server 真的在预期端口上。小结Mastra 冒烟测试的排障逻辑可以归纳为一条主线先对照症状表执行最小修复重部署、重认证、检查部署日志再借助 Trace 查询 API 与mobs-collector日志确认链路到底断在哪一层最后用重部署无效 / 401·404 / 跨项目复现三条标准决定是否升级平台团队。把这份 common-errors.md 与配套的 cloud-deploy.md、traces 测试参考 放在手边绝大多数 smoke test 故障都能在十分钟内定位并修复。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 冒烟测试常见错误与排障指南：Trace 丢失、部署失败到升级策略的完整修复手册
Mastra 冒烟测试常见错误与排障指南Trace 丢失、部署失败到升级策略的完整修复手册【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文基于 Mastra 仓库中 mastra-smoke-test 技能排障文档 展开。该文档是 Mastra 冒烟测试Smoke Test体系中的第一响应手册覆盖本地开发与云端staging/production部署中最常见的故障场景——Trace 不出现、部署挂起、认证失败等。读完本文你将掌握一套可复制的诊断路径按症状定位根因、执行最小修复命令、并在问题无法解决时准确判断是否应该升级给平台团队。一、这份排障手册在 Mastra 冒烟测试体系中的定位在 Mastra 仓库中冒烟测试由 mastra-smoke-test SKILL 组织它定义了一张 12 项的强制测试清单覆盖 Setup、Agents、Tools、Workflows、Traces、Scorers、Memory、MCP、Errors、Experiments、Studio Deploy 与 Server Deploy。其中 Setup 与 Errors 在所有环境下都必须执行Traces、Studio/Server 部署则是云端环境的核心验证项。common-errors.md 就是这套测试体系的快速排障手册它把最常踩的坑浓缩为三张表Trace 问题、部署问题、升级标准。与它配套的还有cloud-deploy.mdstaging/production 部署全流程traces 测试参考Trace 采集与查询的完整协议server 测试参考Server 部署验证步骤gcp-debugging.md需要 GCP 权限时的底层调试入口。排查时遵循的总体原则是先按症状表对号入座执行最小修复命令若修复无效再进入升级流程。下面按这三个层次展开。二、Trace 不出现的三类典型症状Trace可观测性追踪是冒烟测试验证完整链路是否打通的关键证据。测试中一个最经典的场景是在 Studio 的/observability页面先确认 Studio 自身的操作产生 Trace再对已部署的 Server 发起一次 API 调用回到页面确认 Server 产生的 Trace 也出现。如果只见其一链路就有问题。症状一Server traces 缺失但 Studio traces 正常这是最常见的现象说明 Studio 与 Server 两条 Trace 上报链路中Server 一侧的认证凭据失效。文档给出的快速修复是症状可能原因快速修复Server traces 缺失Studio traces 正常Server 上的 token 过期/陈旧重新部署 Serverpnpx mastralatest server deploy -y为什么 Studio 正常而 Server 异常从 cloud-deploy.md 的排查细节可以推断Server 部署时平台会注入MASTRA_CLOUD_ACCESS_TOKEN一个用于 Trace 认证的 JWT若该 token 失效或未正确配置Server 的 trace 上报就会被拒。文档明确列出三个典型信号mobs-collector日志返回POST 200trace 已正常接收返回POST 401JWT 认证失败返回POST 404上报端点错误。若日志中出现401 invalid signature通常是JWT_SECRET 在服务之间不一致若部署日志出现mastra-cloud-observability-exporter disabled则说明平台 API 侧未配置JWT_SECRETServer 拿不到MASTRA_CLOUD_ACCESS_TOKEN。症状二完全没有 trace症状可能原因快速修复完全没有 trace部署时出现可观测性相关警告检查部署日志中是否出现MASTRA_CLOUD_ACCESS_TOKEN警告修复的第一步是回看部署输出。在 server 测试参考 中明确了两条必须记录的关键警告mastra-cloud-observability-exporter disabled—— 表示 trace 不会工作CLOUD_EXPORTER_FAILED_TO_BATCH_UPLOAD_LOGS—— 表示 trace 上报端点存在问题。在本地环境完全没有 trace 通常是另一类原因。根据 local-setup.md本地 trace 默认存储在内存中由MastraStorageExporter提供dev server 重启即丢失。排查本地 trace 缺失按以下顺序检查src/mastra/index.ts中Mastra实例是否配置了可观测性telemetry/observability配置重启 dev server配置变更需要重启生效检查浏览器控制台是否有 OTel 导出错误确认依赖中安装了mastra/observability。当前create-mastra脚手架默认的写法是PinoLoggerObservability含MastraStorageExporter、MastraPlatformExporter、SensitiveDataFilter并使用MastraCompositeStore将默认的 LibSQL 存储与承载observability域的 DuckDB 存储组合起来完整示例可参考 local-setup.md。症状三Studio 日志出现 Session expired症状可能原因快速修复Studio 日志出现 Session expired已知的 cookie 域名问题在 Studio 中重新认证在 cloud-deploy.md 中这一现象被归因于cookie 域名不匹配cookie domain mismatchStudio 需要定期重新认证。它通常与 OAuth 登录后的组织/账号切换问题并存浏览器可能默认登录到错误的账号或组织因此认证后务必校验当前身份cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId}深挖底层Trace 认证与 token 生命周期要真正理解以上症状需要了解云端 Trace 的认证模型。登录后凭据存放在~/.mastra/credentials.json包含token5 分钟过期的访问令牌、refreshToken长效刷新令牌以及user、organizationId等信息。traces 测试参考 提供了get_valid_token辅助函数完整实现了先验证 → 过期则用 refreshToken 刷新 → 刷新失败才重新登录的流程并会把新 token 回写回凭据文件get_valid_token() { local PLATFORM_URL${1:-https://platform.mastra.ai} local TOKEN$(jq -r .token ~/.mastra/credentials.json) local ORG_ID$(jq -r .currentOrgId // .organizationId ~/.mastra/credentials.json) # 先尝试当前 token local VERIFY$(curl -s $PLATFORM_URL/v1/auth/verify \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID) if echo $VERIFY | jq -e .user /dev/null 21; then echo $TOKEN return 0 fi # token 已过期——尝试刷新 local REFRESH_TOKEN$(jq -r .refreshToken ~/.mastra/credentials.json) if [ -z $REFRESH_TOKEN ] || [ $REFRESH_TOKEN null ]; then echo No refresh token. Re-login required. 2 return 1 fi local REFRESH_RESULT$(curl -s $PLATFORM_URL/v1/auth/refresh-token \ -X POST \ -H Content-Type: application/json \ -d {\refreshToken\: \$REFRESH_TOKEN\}) if echo $REFRESH_RESULT | jq -e .accessToken /dev/null 21; then local NEW_TOKEN$(echo $REFRESH_RESULT | jq -r .accessToken) local NEW_REFRESH$(echo $REFRESH_RESULT | jq -r .refreshToken) jq --arg t $NEW_TOKEN --arg r $NEW_REFRESH \ .token $t | .refreshToken $r \ ~/.mastra/credentials.json ~/.mastra/credentials.json.tmp \ mv ~/.mastra/credentials.json.tmp ~/.mastra/credentials.json echo $NEW_TOKEN return 0 fi echo Refresh failed. Re-login required. 2 return 1 }重要实践遇到401时不要急着重新登录登录会打开浏览器 OAuth 流程先用verifyrefresh-token接口尝试无感续期。只有当刷新失败时才执行pnpx mastralatest auth login并且在触发登录前务必提醒用户——因为它会弹出浏览器。直接查询 Trace 接口绕过 UI 验证链路当 UI 上迟迟不显示 trace但又需要确认采集链路本身是否工作可以绕过 Studio 直接查询 trace 接口。本地环境无需认证# 列出最近的 spans响应结构为 { pagination, spans } curl -s http://localhost:4111/api/observability/traces?page0perPage20 | jq . # 快速判定总数 0 且包含预期的 spanType curl -s http://localhost:4111/api/observability/traces?page0perPage100 | \ jq {total: .pagination.total, byType: ([.spans[].spanType] | group_by(.) | map({t: .[0], n: length}))}注意响应形状返回的是{ pagination: { total, page, perPage, hasMore }, spans: [...] }不是裸数组也没有traces键。每条 span 含spanTypeagent_run、tool_call、workflow_run、scorer_run、traceId、时间戳与 payload。云端则需要项目信息与有效 token使用上面的get_valid_tokenPROJECT_ID$(jq -r .projectId .mastra-project.json) # 或 .mastra-project-staging.json ORG_ID$(jq -r .organizationId .mastra-project.json) TOKEN$(get_valid_token https://platform.mastra.ai) curl -s https://mobs-query-vgvrl5lbxq-uc.a.run.app/api/observability/traces?page0perPage10resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .云端响应中几个关键字段metadata.buildId标识 trace 来自 studio 还是 server 的部署、requestContextStudio 触发的 trace 带有认证用户上下文Server 直调的 trace 为 null、statussuccess/error/running。可以用resourceId、runId、startedAtURL 编码的 JSON做过滤。三、部署问题排查部署挂起或超时症状可能原因快速修复部署挂起/超时网络或平台侧问题到平台项目仪表盘projects.mastra.ai确认部署是否实际成功然后重试这是一个先确认结果、再决定动作的场景CLI 超时并不一定代表部署失败平台侧可能已经完成了构建与发布。因此先到仪表盘核对状态再决定是否重试可以避免重复部署造成资源浪费。Cannot determine project name症状可能原因快速修复Cannot determine project name缺少 package.json在项目根目录存在合法 package.json下执行部署命令部署命令依赖项目根目录的package.json推导项目名。若在错误目录执行、或目录缺少 package.jsonCLI 无法确定项目身份就会报此错误。部署命令与多环境配置冒烟测试支持用一个项目同时面向本地、staging、production 三个环境通过独立的配置文件区分详见 SKILL.md 与 cloud-deploy.md环境配置文件平台 API URL部署 URLProduction.mastra-project.jsonhttps://platform.mastra.aiproject.studio.mastra.cloudStaging.mastra-project-staging.jsonhttps://platform.staging.mastra.aiproject.studio.staging.mastra.cloud每个环境拥有独立的 project ID互不干扰。部署前先设置目标环境# production export MASTRA_PLATFORM_API_URLhttps://platform.mastra.ai # staging export MASTRA_PLATFORM_API_URLhttps://platform.staging.mastra.ai部署 Studio 与 Server# Production默认使用 .mastra-project.json pnpx mastralatest studio deploy -y pnpx mastralatest server deploy -y # Staging显式指定配置文件 pnpx mastralatest studio deploy --config .mastra-project-staging.json -y pnpx mastralatest server deploy --config .mastra-project-staging.json -y-y标志用于自动确认设置。部署完成后从输出中记录 URL然后做健康检查# Staging curl https://project.server.staging.mastra.cloud/health # Production curl https://project.server.mastra.cloud/health # 预期响应{success:true}认证失效导致的部署失败若部署时出现 auth 错误文档给出的标准修复是登出后重新登录再重试pnpx mastralatest auth logout pnpx mastralatest auth login # 会打开浏览器 OAuth执行前先提醒用户部署相关的两个高频伪错误在 cloud-deploy.md 中记录了另外两个与部署相关的常见问题自定义路由静默失效自定义路由必须放在apiRoutes而不是routes字段中否则路由静默不注册且没有任何报错server: { apiRoutes: [helloRoute], // ✅ 正确 // routes: [helloRoute], // ❌ 错误——静默失败 }CORS 错误Server 部署通过SERVER_WRAPPER注入 CORS 配置。遇到 CORS 错误时先检查部署上的MASTRA_CORS_ORIGIN环境变量是否正确并确认来源域名与 Studio 域名模式匹配。四、Server API 验证与 Trace 链路校验部署完成后冒烟测试的 Server 验证遵循健康检查 → Agent API → 脚本化测试 → 回 Studio 看 trace的固定顺序。仓库提供了现成的验证脚本 test-server.sh.claude/skills/mastra-smoke-test/scripts/test-server.sh server-url [agent-id] [message] # 示例 .claude/skills/mastra-smoke-test/scripts/test-server.sh https://my-app.server.staging.mastra.cloud .claude/skills/mastra-smoke-test/scripts/test-server.sh https://my-app.server.mastra.cloud weather-agent Weather in Tokyo?该脚本依次执行检查依赖curl、jq→ 检查/health端点 → 调用 Agent 的/generate端点使用jq构造 JSON 以避免消息中的特殊字符问题→ 解析并展示响应 → 任一环节失败即退出并返回非零状态码。它的默认参数是 agent 为weather-agent、消息为What is the weather in Paris?与你用create-mastra脚手架生成的项目开箱即用。也可以直接 curl 验证核心端点server 测试参考 中的端点清单端点方法用途/healthGET健康检查/api/agents/id/generatePOSTAgent 生成/api/agents/id/streamPOST流式生成/custom-routeANY自定义 API 路由curl -X POST server-url/api/agents/weather-agent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:Weather in Tokyo?}]}最后一步是关键回到 Studio 的/observability页面并刷新确认 Server API 调用产生的 trace 出现。区分来源的方式是来源如何产生如何识别Studio tracesStudio UI 交互聊天、工具运行从 Studio 域名发起Server traces直接调用已部署 Server 的 API从 Server 域名发起如果只有 Studio traces说明 Server 的 trace 上报链路有问题参见上一章的 token 排查。另需注意 Server 冷启动可能耗时 1030 秒首次请求可能较慢trace 最多可能延迟约 30 秒出现排查前先留出等待窗口。五、何时升级到平台团队排障手册明确了快速修复无效时的升级标准。当出现以下任一情况应当联系平台团队而不是继续在应用层反复尝试重新部署无法修复 trace 问题部署日志中出现401或404错误问题跨多个项目持续存在。第一条表明问题不在单个部署实例的凭据而在更上层的配置第二条中的401认证失败与404端点错误往往对应平台侧服务的 JWT 配置或端点路由问题见第二章的mobs-collector日志解读第三条则说明问题具有系统性质而非特定项目的数据或配置问题。当排障需要进入基础设施层面例如查看mobs-collector日志、核对JWT_SECRET配置时需要GCP Console 访问权限。完整的内部基础设施调试指南见 gcp-debugging.md其中明确了什么时候该查 GCP 日志Server traces 不出现、部署静默失败、认证/会话问题。若你没有 GCP 权限应当联系具有基础设施访问权限的团队成员协助。六、附错误处理测试的断言基线common-errors.md将部署日志中的401/404列为升级信号而Errors测试errors.md则给出了应用层各错误场景的预期 HTTP 状态码基线二者互为补充——前者判断平台健康度后者验证应用自身的错误映射质量场景HTTP响应体形态未知 agent id404{ error: Agent with id id not found }或类似未知 tool id404{ error: Tool not found }未知 workflow id404{ error: Workflow not found }Workflow 缺少必填输入500{ error: Invalid input data: field expected ... }Tool 缺少必填输入200{ error: true, validationErrors: { ... } }JSON 体非法400{ error: ... }Hono body 解析失败文档特别标注了两处已知的不一致/潜在缺陷可作为回归监测点Tool 无效输入返回200且 body 中带error: true与 workflow/agent 的 HTTP 语义不一致Workflow schema 校验失败返回500属于潜在的服务端/API 错误映射 bug——客户端输入导致的校验失败按惯例应映射为 4xx。无论哪种场景通过标准都是每个错误响应都包含可读的error字段tool 用validationErrors、响应体中不泄露堆栈信息、HTTP 状态码与上表一致或存在已记录的偏差。七、附环境变量与快速命令速查排障过程中最容易搞混的是哪些变量该自己设、哪些平台会自动注入。根据 environment-variables.md需要手动设置的变量变量用途设置时机MASTRA_PLATFORM_API_URL指定目标是 staging 还是 production在mastra auth login之前OPENAI_API_KEYLLM API 访问运行 agents 之前ANTHROPIC_API_KEY备选 LLM若使用 Anthropic平台部署时自动注入、无需手动设置的变量MASTRA_CLOUD_ACCESS_TOKEN—— 用于 trace 认证的 JWTMASTRA_CLOUD_TRACES_ENDPOINT—— trace 上报端点。常用检查命令# 确认目标环境 echo $MASTRA_PLATFORM_API_URL # 确认登录状态 mastra auth status # 确认凭据身份 cat ~/.mastra/credentials.json | jq {email: .user.email, organizationId} # 本地确认 :4111 上没有残留的 dev server端口被占用会静默换到 4112导致 curl 打错项目 lsof -i :4111最后一条值得单独强调mastra dev在:4111被占用时会自动递增端口如果没察觉后续 curl 都会命中之前测试会话残留的旧项目产生错误不在你怀疑的地方的假象。按 local-setup.md 的建议先清理端口再启动并用curl -s -o /dev/null -w HTTP %{http_code}\n http://localhost:4111/api/agents预期 200确认 dev server 真的在预期端口上。小结Mastra 冒烟测试的排障逻辑可以归纳为一条主线先对照症状表执行最小修复重部署、重认证、检查部署日志再借助 Trace 查询 API 与mobs-collector日志确认链路到底断在哪一层最后用重部署无效 / 401·404 / 跨项目复现三条标准决定是否升级平台团队。把这份 common-errors.md 与配套的 cloud-deploy.md、traces 测试参考 放在手边绝大多数 smoke test 故障都能在十分钟内定位并修复。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考