{"record":{"id":"cc8f26b082110e25","repo":"mastra-ai/mastra","slug":"failed-to-observe-agent-builder-action-stream-r","errorCode":null,"errorMessage":"Failed to observe agent builder action stream: ${response.statusText}","messagePattern":"Failed to observe agent builder action stream: (.+?)","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/client-js/src/resources/agent-builder.ts","lineNumber":233,"sourceCode":"\n  /**\n   * Observes an existing agent builder action run stream.\n   * Replays cached execution from the beginning, then continues with live stream.\n   * This is the recommended method for recovery after page refresh/hot reload.\n   * This calls `/agent-builder/:actionId/observe`\n   */\n  async observeStream(params: { runId: string }): Promise<globalThis.ReadableStream<{ type: string; payload: any }>> {\n    const searchParams = new URLSearchParams();\n    searchParams.set('runId', params.runId);\n\n    const url = `/agent-builder/${this.actionId}/observe?${searchParams.toString()}`;\n    const response: Response = await this.request(url, {\n      method: 'POST',\n      stream: true,\n    });\n\n    if (!response.ok) {\n      throw new Error(`Failed to observe agent builder action stream: ${response.statusText}`);\n    }\n\n    if (!response.body) {\n      throw new Error('Response body is null');\n    }\n\n    return response.body.pipeThrough(this.createRecordParserTransform());\n  }\n\n  /**\n   * Observes an existing agent builder action run stream using legacy streaming API.\n   * Replays cached execution from the beginning, then continues with live stream.\n   * This calls `/agent-builder/:actionId/observe-stream-legacy`.\n   */\n  async observeStreamLegacy(params: {\n    runId: string;\n  }): Promise<globalThis.ReadableStream<{ type: string; payload: any }>> {\n    const searchParams = new URLSearchParams();","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/client-js/src/resources/agent-builder.ts#L215-L251","documentation":"observeStream() POSTs to the agent-builder action stream endpoint with stream:true and throws this error when the HTTP response status is not ok (response.ok is false). It surfaces only response.statusText, so the server rejected the streaming request before any stream data was produced. This is a transport/HTTP-level guard that fails fast instead of trying to parse a non-stream body.","triggerScenarios":"Calling observeStream() on a ClientAgentBuilderResource when the server returns a non-2xx status: wrong/missing auth credentials, invalid action id or route path, agent-builder feature not enabled on the server, server crash or proxy returning 4xx/5xx for the streaming POST.","commonSituations":"Mastra server not running or deployed with agent-builder disabled; expired API key against packages/server; request hitting an older server without the agent-builder stream route; corporate proxy or gateway aborting long-lived streaming POSTs.","solutions":["Check response.statusText plus the server logs for the actual HTTP status; fix the underlying 4xx/5xx (auth, route, payload).","Verify the Mastra server version supports the agent-builder observe endpoint and that the URL/base path is correct.","Confirm authentication credentials passed to MastraClient are valid and scoped for agent-builder routes.","Retry with backoff if statusText indicates 502/503/504 from an intermediate proxy.","Wrap the call in try/catch and surface the status to the user instead of letting the stream hang."],"exampleFix":"// before\nconst stream = await client.getAgentBuilder().observeStream(params); // throws bare statusText\n// after\ntry {\n  const stream = await client.getAgentBuilder().observeStream(params);\n} catch (e) {\n  console.error('observeStream failed:', (e as Error).message, '— check server status/auth for agent-builder routes');\n}","handlingStrategy":"try-catch","validationCode":"// nothing to validate client-side besides reachability\nconst health = await fetch(`${clientUrl}/health`).then(r => r.ok).catch(() => false);\nif (!health) throw new Error('Mastra server unreachable before observing agent builder stream');","typeGuard":"function isOkResponse(res: Response): res is Response & { ok: true } { return res.ok; }","tryCatchPattern":"try {\n  const stream = await builder.observeStream(params);\n} catch (err) {\n  console.error(`observeStream failed: ${(err as Error).message}`);\n  // inspect server logs for the HTTP status; retry on 5xx, fail fast on 4xx\n}","preventionTips":["Verify server health and auth before starting long-lived streams","Pin SDK and server versions so agent-builder routes exist","Retry with backoff only on transient 5xx statuses","Log response.statusText alongside request context for triage"],"tags":["http","streaming","network","client-js"],"backgroundTag":"http-non-ok-response","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}