mastra-ai/mastra · error

OpenAISDKAgent resumeData must include previousResponseId, c

Error message

OpenAISDKAgent resumeData must include previousResponseId, conversationId, or session.

What it means

The OpenAI SDK Agent wrapper requires resume data that points at an existing OpenAI conversation context. validateOpenAIResumeData checks that the passed resumeData object contains at least one of previousResponseId (string), conversationId (string), or session (defined). If none are present, resuming has nothing to continue from, so the library throws immediately instead of issuing a doomed API call.

Source

Thrown at agent-sdks/openai/src/index.ts:257

): OpenAIStructuredOutputOption<OUTPUT> | undefined {
  return options?.structuredOutput as OpenAIStructuredOutputOption<OUTPUT> | undefined;
}

function validateOpenAIResumeData(resumeData: OpenAISDKAgentResumeData): OpenAISDKAgentResumeData {
  const record = toRecord(resumeData);
  if (!record || !('message' in record)) {
    throw new Error('OpenAISDKAgent resumeData must include a message.');
  }

  if (
    typeof resumeData.previousResponseId === 'string' ||
    typeof resumeData.conversationId === 'string' ||
    resumeData.session !== undefined
  ) {
    return resumeData;
  }

  throw new Error('OpenAISDKAgent resumeData must include previousResponseId, conversationId, or session.');
}

function createOpenAIResumeRunOptions<OUTPUT>(
  resumeData: OpenAISDKAgentResumeData,
  options?: SDKAgentRunOptions<OUTPUT>,
): SDKAgentRunOptions<OUTPUT> {
  return {
    ...options,
    previousResponseId: resumeData.previousResponseId ?? options?.previousResponseId,
    conversationId: resumeData.conversationId ?? options?.conversationId,
    session: resumeData.session ?? options?.session,
  };
}

async function runOpenAIGenerate<OUTPUT>(
  prompt: string,
  agent: OpenAIAgent,
  runId: string,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Capture the resume handle from the original run's result (previousResponseId, conversationId, or session) and store it alongside your application state.
2. Pass one of the three accepted fields in resumeData, e.g. { previousResponseId: 'resp_abc123' } — a stored session object also works.
3. Validate the persisted payload shape before deserializing/resuming; drop or re-create conversations with no stored handle.
4. If using run options instead, note that options-level previousResponseId/conversationId/session are only merged AFTER resumeData validates, so options alone do not bypass this check.

Example fix

// before
await agent.resume({}) as unknown;
// after
await agent.resume({ previousResponseId: result.responseId });

function canResume(d) {
  return d != null &&
    (typeof d.previousResponseId === 'string' ||
     typeof d.conversationId === 'string' ||
     d.session !== undefined);
}
if (!canResume(storedResumeData)) {
  throw new Error('No stored resume context; start a new run instead.');
}

function isOpenAIResumeData(d: unknown): d is { previousResponseId: string } {
  return typeof d === 'object' && d !== null &&
    ('previousResponseId' in d || 'conversationId' in d || 'session' in d);
}

try {
  await agent.resume(resumeData);
} catch (err) {
  if (err instanceof Error && err.message.includes('resumeData must include')) {
    result = await agent.generate(prompt); // fall back to fresh run
  } else throw err;
}

When it happens

Trigger: Calling a resume/streamResume method on OpenAISDKAgent with an empty object, an object with only unrelated fields (e.g. { threadId: '...' }), or fields set to null/undefined — i.e. resumeData where previousResponseId and conversationId are not strings and session is undefined.

Common situations: Persisting the agent result but forgetting to store previousResponseId; renaming or migrating fields in your own storage layer; passing a resume payload built for a different provider's agent (e.g. Claude thread IDs) into the OpenAI wrapper; TypeScript not catching it because resumeData was cast from a loosely-typed record or fetched from JSON.

Related errors

• OpenAISDKAgent resumeData must include a message.
• ClaudeSDKAgent resumeData must include sessionId or continue
• CursorSDKAgent resumeData must include a message.
• CursorSDKAgent resumeData.agentId must be a string when prov
• runId is required when resumeData is provided

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/990aefe9738bf077. Report an issue: GitHub.