mastra-ai/mastra · error

ClaudeSDKAgent resumeData.sessionId must be a string.

Error message

ClaudeSDKAgent resumeData.sessionId must be a string.

What it means

The restore handler fetches the version to restore with getVersion(versionId); when it returns null the endpoint returns 404 with this message. Nothing can be restored because the version record is absent.

Source

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

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

function createClaudeResumeRunOptions<OUTPUT>(
  resumeData: ClaudeSDKAgentResumeData,
  options?: ClaudeSDKAgentRunOptions<OUTPUT>,
): ClaudeSDKAgentRunOptions<OUTPUT> {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Fetch GET /api/agents/:agentId/versions and pick an existing versionId
2. Fix the versionId path parameter
3. Connect to the storage environment that contains the version history
4. Re-snapshot the agent configuration to create a new version to restore

Example fix

// before
restore(versionId); // invented id
// after
const versions = await fetch(`/api/agents/${agentId}/versions`).then(r => r.json());
if (versions.length) restore(versions[0].id);

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

function restorable(versions: {id: string}[], versionId: string): boolean {
  return versions.some(v => v.id === versionId);
}

try {
  await fetch(`/api/agents/${agentId}/versions/${versionId}/restore`, { method: 'POST' });
} catch (e) {
  if (isHttpError(e) && e.status === 404 && /Version with id .* not found$/.test(e.message)) {
    // list versions and choose a valid one
  } else throw e;
}

When it happens

Trigger: POST restore where :versionId doesn't exist in the agents store for any agent.

Common situations: Version data purged by cleanup jobs; restoring from a fresh database that never recorded that version; copying versionIds between environments.

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
• Model "${this.options.model}" is not available. Available mo
• ClaudeSDKAgent resumeData.continue must be true when provide
• Version with id ${from} not found
• Version with id ${to} not found

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