{"record":{"id":"7d5134a71748f4b3","repo":"mastra-ai/mastra","slug":"error","errorCode":null,"errorMessage":"error","messagePattern":"error","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/client-js/src/resources/agent.ts","lineNumber":1643,"sourceCode":"      onStartStepPart(value) {\n        // keep message id stable when we are updating an existing message:\n        if (!replaceLastMessage) {\n          message.id = value.messageId;\n        }\n\n        // add a step boundary part to the message\n        message.parts.push({ type: 'step-start' });\n        execUpdate();\n      },\n      onFinishMessagePart(value) {\n        finishReason = value.finishReason;\n        if (value.usage != null) {\n          // usage = calculateLanguageModelUsage(value.usage);\n          usage = value.usage;\n        }\n      },\n      onErrorPart(error) {\n        throw new Error(error);\n      },\n    });\n\n    onFinish?.({ message, finishReason, usage });\n  }\n\n  /**\n   * Streams a response from the agent\n   * @param params - Stream parameters including prompt\n   * @returns Promise containing the enhanced Response object with processDataStream method\n   */\n  async streamLegacy<T extends JSONSchema7 | ZodSchema | undefined = undefined>(\n    params: StreamLegacyParams<T>,\n  ): Promise<\n    Response & {\n      processDataStream: (options?: Omit<Parameters<typeof processDataStream>[0], 'stream'>) => Promise<void>;\n    }\n  > {","sourceCodeStart":1625,"sourceCodeEnd":1661,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/client-js/src/resources/agent.ts#L1625-L1661","documentation":"The stream emitted an 'error' part, and onErrorPart re-throws it verbatim, so the exposed message equals the server-side error text (here the literal 'error'). Any failure the server pushes into the stream (LLM failure, tool failure, auth problem) surfaces as this thrown Error instead of a rejected fetch.","triggerScenarios":"Calling agent.stream/streamVNext (generate path at this line) when the server emits { type: 'error', message: 'error' } during data stream processing — typically a server-side agent/tool/model failure relayed into the stream.","commonSituations":"Expired or missing auth causing server-side failure; LLM provider error inside a tool or workflow executed server-side; network interruption mid-stream causing the server to write an error part; server configured to send opaque error messages.","solutions":["Inspect the server logs / trace for the run to find the underlying cause, since the client only sees the relayed message.","Add an onError handler in your consume options instead of relying on the throw, to handle stream errors gracefully.","Check API keys, model configuration, and tool implementations on the server.","Retry the request with backoff if the cause was transient (network or provider 5xx)."],"exampleFix":"// before\nawait agent.stream({ messages }).consume({ onErrorPart: e => { throw new Error(e); } });\n// after\ntry {\n  await agent.stream({ messages }).consume({ onErrorPart: e => log.warn('stream error part', e) });\n} catch (err) {\n  log.error('stream failed', err);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isStreamErrorPart(part: unknown): part is { type: 'error'; message: string } {\n  return typeof part === 'object' && part !== null && (part as any).type === 'error';\n}","tryCatchPattern":"try {\n  await agent.stream({ messages }).consume({ onFinish });\n} catch (err) {\n  console.error('Agent stream emitted an error part:', err.message);\n  // check server logs/traces for the underlying cause\n}","preventionTips":["Monitor server-side logs and traces for the run that produced the error part.","Validate API keys, model config, and tool implementations before long-running streams.","Handle error parts in onErrorPart explicitly instead of letting them throw uncaught.","Implement retry with backoff for transient provider/network failures."],"tags":["streaming","server-error","error-part"],"backgroundTag":"stream-error-part","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}