mastra-ai/mastra · error

ClaudeSDKAgent resumeData must include sessionId or continue

Error message

ClaudeSDKAgent resumeData must include sessionId or continue: true.

What it means

ClaudeSDKAgent.resume() requires resumeData that either carries a sessionId (to restore a previous Claude Agent SDK session) or has continue set to true (to continue the most recent conversation). validateClaudeResumeData throws this when neither is present, meaning the agent has no conversation context to resume from.

Source

Thrown at agent-sdks/claude/src/index.ts:263

  if (hasSessionId && hasContinue) {
    throw new Error('ClaudeSDKAgent resumeData must include either sessionId or continue: true, not both.');
  }

  if (hasSessionId) {
    if (typeof resumeData.sessionId !== 'string') {
      throw new Error('ClaudeSDKAgent resumeData.sessionId must be a string.');
    }
    return resumeData;
  }

  if (hasContinue) {
    if (resumeData.continue !== true) {
      throw new Error('ClaudeSDKAgent resumeData.continue must be true when provided.');
    }
    return resumeData;
  }

  throw new Error('ClaudeSDKAgent resumeData must include sessionId or continue: true.');
}

function createClaudeResumeRunOptions<OUTPUT>(
  resumeData: ClaudeSDKAgentResumeData,
  options?: ClaudeSDKAgentRunOptions<OUTPUT>,
): ClaudeSDKAgentRunOptions<OUTPUT> {
  const sdkOptions: ClaudeSDKOptions = { ...options?.sdkOptions };

  if ('sessionId' in resumeData && typeof resumeData.sessionId === 'string') {
    sdkOptions.resume = resumeData.sessionId;
    if (resumeData.forkSession !== undefined) {
      sdkOptions.forkSession = resumeData.forkSession;
    }
    if (resumeData.resumeSessionAt !== undefined) {
      sdkOptions.resumeSessionAt = resumeData.resumeSessionAt;
    }
  } else {
    sdkOptions.continue = true;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass the sessionId returned from the previous ClaudeSDKAgent run in resumeData.
2. If you want to continue the latest conversation instead, pass { continue: true } (exactly true, not truthy).
3. Verify the saved resumeData shape before resuming — it must satisfy ClaudeSDKAgentResumeData with at least one of sessionId or continue: true.

Example fix

// before
await agent.resume({ threadId });
// after
await agent.resume({ sessionId: savedState.sessionId });

function canResumeClaude(data: unknown): data is { sessionId?: string; continue?: true } {
  return typeof data === 'object' && data !== null &&
    (('sessionId' in data) || (data as any).continue === true);
}
if (!canResumeClaude(saved)) throw new Error('No sessionId or continue:true saved');
await agent.resume(saved);

function isClaudeResumeData(v: unknown): v is ClaudeSDKAgentResumeData {
  if (typeof v !== 'object' || v === null) return false;
  const d = v as Record<string, unknown>;
  return (typeof d.sessionId === 'string') || d.continue === true;
}

try {
  await agent.resume(saved);
} catch (e) {
  if (e instanceof Error && e.message.includes('resumeData must include sessionId')) {
    // fall back to starting a fresh conversation
    await agent.generate(prompt);
  } else throw e;
}

When it happens

Trigger: Calling claudeSDKAgent.resume({ ... }) with an empty object, with an object missing both sessionId and continue, or with continue set to a value other than true (which triggers the sibling 'continue must be true' error first).

Common situations: Persisting only the thread/model metadata instead of the Claude sessionId when checkpointing a conversation; hand-constructing resumeData after a restart; copying resume patterns from other agent SDKs where resumeData shape differs.

Related errors

• CursorSDKAgent resumeData must include a message.
• OpenAISDKAgent resumeData must include a message.
• CursorSDKAgent resumeData.agentId must be a string when prov
• OpenAISDKAgent resumeData must include previousResponseId, c
• runId is required when resumeData is provided

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