ClaudeSDKAgent resumeData must include either sessionId or c

Error message

ClaudeSDKAgent resumeData must include either sessionId or continue: true, not both.

What it means

The restore handler verifies the agent exists via agentsStore.getById before restoring; a null result produces this 404. The restore target agent must exist in storage.

Source

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

  async resumeStream<OUTPUT = undefined>(
    resumeData: ClaudeSDKAgentResumeData,
    options?: ClaudeSDKAgentRunOptions<OUTPUT>,
  ): Promise<MastraModelOutput<OUTPUT>> {
    const data = validateClaudeResumeData(resumeData);
    return this.stream(data.message, createClaudeResumeRunOptions(data, options));
  }
}

function validateClaudeResumeData(resumeData: ClaudeSDKAgentResumeData): ClaudeSDKAgentResumeData {
  if (!isRecord(resumeData) || !('message' in resumeData)) {
    throw new Error('ClaudeSDKAgent resumeData must include a message.');
  }

  const hasSessionId = 'sessionId' in resumeData;
  const hasContinue = 'continue' in resumeData;

  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.');
}

View on GitHub (pinned to 75dd419e61)

Solutions

Confirm the agentId via GET /api/agents before restoring
Correct the path parameter
Point the server at the storage environment containing the agent
Recreate the agent record if it was deleted

Example fix

// before
await fetch(`/api/agents/${staleAgentId}/versions/${vId}/restore`, { method: 'POST' });
// after
const exists = (await fetch('/api/agents').then(r => r.json())).some(a => a.id === staleAgentId);
if (exists) await fetch(`/api/agents/${staleAgentId}/versions/${vId}/restore`, { method: 'POST' });

Defensive patterns

Strategy: validation

Validate before calling

const agents = await fetch('/api/agents').then(r => r.json());
if (!agents.some(a => a.id === agentId)) throw new Error(`Cannot restore: agent ${agentId} missing`);

Type guard

function canRestore(agents: {id: string}[], agentId: string): boolean {
  return agents.some(a => a.id === agentId);
}

Try / catch

try {
  await fetch(`/api/agents/${agentId}/versions/${versionId}/restore`, { method: 'POST' });
} catch (e) {
  if (isHttpError(e) && e.status === 404 && e.message.includes('Agent with id')) {
    // recreate agent or fix agentId before retrying
  } else throw e;
}

Prevention

Check agent existence before restore calls
Guard cleanup jobs from deleting agents with active version references
Use ids sourced from the same environment as the target storage
Confirm DB connection env vars match the intended environment

When it happens

Trigger: POST restore on /api/agents/:agentId/versions/:versionId where :agentId is not present in the agents store.

Common situations: Deleting an agent then replaying old client requests; wrong environment/database; misspelled or stale agentId in the client.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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