{"record":{"id":"8313bfdb985a9ae2","repo":"mastra-ai/mastra","slug":"runid-is-required-when-resumedata-is-provided","errorCode":null,"errorMessage":"runId is required when resumeData is provided","messagePattern":"runId is required when resumeData is provided","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/ai-sdk/src/chat-route.ts","lineNumber":298,"sourceCode":"  agentId,\n  agentVersion,\n  params,\n  defaultOptions,\n  experimentalTransform,\n  version = 'v5',\n  sendStart = true,\n  sendFinish = true,\n  sendReasoning = false,\n  sendSources = false,\n  onError,\n  messageMetadata,\n}: Omit<ChatStreamHandlerOptions<any, OUTPUT>, 'messageMetadata'> & {\n  messageMetadata?: any;\n}): Promise<ReadableStream<any>> {\n  const { messages, resumeData, runId, requestContext, trigger, ...rest } = params;\n\n  if (resumeData && !runId) {\n    throw new Error('runId is required when resumeData is provided');\n  }\n\n  const baseAgent = mastra.getAgentById(agentId);\n  if (!baseAgent) {\n    throw new Error(`Agent ${agentId} not found`);\n  }\n\n  // When an editor is configured, an agent's runtime config (instructions, tools,\n  // model, ...) can live in stored config rather than the code definition. Studio\n  // resolves these stored overrides before every run, so this endpoint must do the\n  // same or it would execute a stale/empty code-defined agent (issue #18574). An\n  // explicit agentVersion (from query params or route options) wins; otherwise we\n  // default to the published version, matching the built-in agent handlers.\n  let agentObj = baseAgent;\n  const editorAgent = mastra.getEditor?.()?.agent;\n  if (editorAgent) {\n    agentObj = await editorAgent.applyStoredOverrides(\n      baseAgent,","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/chat-route.ts#L280-L316","documentation":"The AI SDK chat route handler accepts resumeData to resume a previously interrupted agent run. Resuming requires identifying which run to resume, supplied via runId. Providing resumeData without runId is ambiguous and rejected at the start of handleChatStream before any agent lookup.","triggerScenarios":"POSTing to the chat route with a body containing resumeData but omitting runId; frontend resume logic that sends the saved resume payload from storage but loses the runId field.","commonSituations":"Custom resume UIs that persisted resumeData but not runId; older clients predating the runId requirement; manual curl/testing payloads that include partial resume state.","solutions":["Include the runId field in the request body alongside resumeData","On the client, persist both runId and resumeData together when a stream is interrupted, and send both when resuming","If the request is not meant to resume, remove resumeData from the payload","Update the client SDK version so resume helpers include runId automatically"],"exampleFix":"// before\nresumeChat({ resumeData: saved.resumeData })\n// after\nresumeChat({ runId: saved.runId, resumeData: saved.resumeData })","handlingStrategy":"validation","validationCode":"if (body.resumeData && !body.runId) {\n  throw new Error('runId must accompany resumeData');\n}","typeGuard":"function canResume(b: { resumeData?: unknown; runId?: string }): b is { resumeData: unknown; runId: string } {\n  return b.resumeData === undefined || typeof b.runId === 'string' && b.runId.length > 0;\n}","tryCatchPattern":"try {\n  const stream = await handleChatStream({ ...params, resumeData, runId });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('runId is required')) {\n    // fall back to starting a fresh run without resumeData\n  }\n}","preventionTips":["Persist runId together with resumeData whenever a stream is interrupted","Type the client request body so resumeData requires runId","In resume UIs, disable the resume action when runId is missing","Prefer the AI SDK client helpers, which manage runId automatically"],"tags":["ai-sdk","validation","resume","request-body"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}