mastra-ai/mastra · error

ClaudeSDKAgent resumeData.continue must be true when…

Error message

ClaudeSDKAgent resumeData.continue must be true when provided.

What it means

The version record exists but belongs to a different agent than :agentId; the restore handler returns 404 with this message (same masking rationale as the get handler) to avoid disclosing versions across agents.

Solutions

1. Ensure versionId comes from the same agent's version list as agentId
2. Correct :agentId to the agent the version belongs to
3. Clear/refresh stale client state before retrying
4. Validate pairing client-side (version.agentId === agentId) before calling the endpoint

Example fix

// before
await fetch(`/api/agents/${agentA.id}/versions/${versionOfB.id}/restore`, { method: 'POST' });
// after
if (versionOfB.agentId === agentA.id) {
  await fetch(`/api/agents/${agentA.id}/versions/${versionOfB.id}/restore`, { method: 'POST' });
}

const versions = await fetch(`/api/agents/${agentId}/versions`).then(r => r.json());
if (!versions.some(v => v.id === versionId)) {
  throw new Error(`Version ${versionId} does not belong to agent ${agentId}`);
}

function isOwnedVersion(v: {id: string; agentId: string} | undefined, agentId: string): v is {id: string; agentId: string} {
  return !!v && v.agentId === agentId;
}

try {
  await fetch(`/api/agents/${agentId}/versions/${versionId}/restore`, { method: 'POST' });
} catch (e) {
  if (isHttpError(e) && e.status === 404 && e.message.includes('not found for agent')) {
    // correct the agentId/versionId pairing before retrying
  } else throw e;
}

When it happens

Trigger: POST restore on /api/agents/:agentId/versions/:versionId where version.agentId !== agentId.

Common situations: Client mixing selection state across agents; reusing a versionId after the agent was duplicated/recreated under a new id; programmatic scripts iterating mismatched id pairs.

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

• ACP connection is not initialized
• ClaudeSDKAgent resumeData.sessionId must be a string.
• Model " " is not available. Available models
• Version with id not found
• Version with id not found

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

Appendix: source

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

  }

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

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;
    }

View on GitHub (pinned to 75dd419e61)