{"record":{"id":"2b6eefa37aef8511","repo":"mastra-ai/mastra","slug":"failed-to-observe-agent-builder-action-stream-lega","errorCode":null,"errorMessage":"Failed to observe agent builder action stream legacy: ${response.statusText}","messagePattern":"Failed to observe agent builder action stream legacy: (.+?)","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/client-js/src/resources/agent-builder.ts","lineNumber":261,"sourceCode":"  /**\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();\n    searchParams.set('runId', params.runId);\n\n    const url = `/agent-builder/${this.actionId}/observe-stream-legacy?${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 legacy: ${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   * Resumes a suspended agent builder action and streams the results.\n   * This calls `/agent-builder/:actionId/resume-stream`.\n   */\n  async resumeStream(params: {\n    runId: string;\n    step: string | string[];\n    resumeData?: unknown;\n    requestContext?: RequestContext;","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/client-js/src/resources/agent-builder.ts#L243-L279","documentation":"observeStreamLegacy() performs the same ok-check as observeStream but against the legacy agent-builder stream endpoint, throwing this error when the HTTP status is not ok. It exists for backward compatibility and is called by stream(). The message distinguishes the legacy route so failures can be attributed to it.","triggerScenarios":"Calling stream() (which delegates to observeStreamLegacy) when the legacy endpoint returns non-2xx: server removed or disabled the legacy route, wrong action/record id, auth failure, or proxy error on the streaming POST.","commonSituations":"Server upgraded to the new agent-builder stream API and legacy route returns 404/410; clients pinned to old SDK shapes hitting new servers; expired credentials; gateway timeouts on long-lived streams.","solutions":["Check the HTTP status in server logs; fix auth/route/payload accordingly.","If the server removed the legacy route, migrate to the non-legacy observeStream API.","Confirm SDK and server versions are compatible (legacy endpoint availability).","Retry with backoff for transient 5xx from proxies.","Catch and log the statusText with request context before surfacing to users."],"exampleFix":"// before\nconst stream = await builder.stream(params); // legacy path throws bare statusText\n// after\ntry {\n  const stream = await builder.stream(params);\n} catch (e) {\n  console.error('legacy observe stream failed:', (e as Error).message);\n  // fall back to non-legacy API if server no longer supports it\n  const stream2 = await builder.observeStream(params);\n}","handlingStrategy":"try-catch","validationCode":"const legacyAvailable = await fetch(`${base}/agent-builder/stream/legacy-probe`, { method: 'OPTIONS' }).then(r => r.ok).catch(() => false);\nif (!legacyAvailable) console.warn('Legacy agent-builder stream route unavailable; use observeStream');","typeGuard":"function isOkResponse(res: Response): res is Response & { ok: true } { return res.ok; }","tryCatchPattern":"try {\n  const stream = await builder.stream(params);\n} catch (err) {\n  console.error(`legacy stream failed: ${(err as Error).message}`);\n  const stream = await builder.observeStream(params); // migrate/fallback\n}","preventionTips":["Prefer the current observeStream API over legacy routes","Keep client and server versions aligned","Check for 404/410 statuses indicating removed legacy endpoints","Log statusText with the request URL for triage"],"tags":["http","streaming","legacy","network"],"backgroundTag":"http-non-ok-response","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}