mastra-ai/mastra · error · HTTPException

Version with id ${from} not found

Error message

Version with id ${from} not found

What it means

The diff handler resolves the 'from' version before the 'to' version. If agentsStore.getVersion(from) returns null, the source version of the comparison doesn't exist and the endpoint returns a 404 naming the from id.

Source

Thrown at packages/server/src/server/handlers/agent-versions.ts:534

  handler: async ({ mastra, agentId, from, to, requestContext }) => {
    try {
      const storage = mastra.getStorage();

      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }

      const agentsStore = await storage.getStore('agents');
      if (!agentsStore) {
        throw new HTTPException(500, { message: 'Agents storage domain is not available' });
      }
      const agent = await agentsStore.getById(agentId);
      assertStoredResourceScope(agent, await getStoredResourceScope(mastra, requestContext));

      // Get both versions
      const fromVersion = await agentsStore.getVersion(from);
      if (!fromVersion) {
        throw new HTTPException(404, { message: `Version with id ${from} not found` });
      }
      if (fromVersion.agentId !== agentId) {
        throw new HTTPException(404, { message: `Version with id ${from} not found for agent ${agentId}` });
      }

      const toVersion = await agentsStore.getVersion(to);
      if (!toVersion) {
        throw new HTTPException(404, { message: `Version with id ${to} not found` });
      }
      if (toVersion.agentId !== agentId) {
        throw new HTTPException(404, { message: `Version with id ${to} not found for agent ${agentId}` });
      }

      // Extract config fields from both versions (top-level, no .snapshot)
      const fromConfig = extractConfigFromVersion(
        fromVersion as unknown as Record<string, unknown>,
        SNAPSHOT_CONFIG_FIELDS,
      );

View on GitHub (pinned to 75dd419e61)

Solutions

  1. List current versions (GET /api/agents/{agentId}/versions) and pick a valid from id
  2. Lower the retention limit or stop pruning if older versions must remain diffable
  3. Confirm the request hits the intended storage backend/environment
  4. Check for typos or swapped from/to parameters
Defensive patterns

Strategy: validation

Validate before calling

const versions = await (await fetch(`/api/agents/${agentId}/versions`)).json();
if (!versions.some((v: { id: string }) => v.id === from)) {
  throw new Error(`'from' version ${from} does not exist for agent ${agentId}`);
}
if (!versions.some((v: { id: string }) => v.id === to)) {
  throw new Error(`'to' version ${to} does not exist for agent ${agentId}`);
}

Type guard

function diffable(versions: { id: string }[], from: string, to: string): boolean {
  return versions.some(v => v.id === from) && versions.some(v => v.id === to);
}

Try / catch

try {
  const res = await fetch(`/api/agents/${agentId}/versions/diff?from=${from}&to=${to}`);
  if (res.status === 404 && (await res.json()).message.includes(`Version with id ${from} not found`)) {
    // refresh version list; the 'from' version may have been pruned
  }
} catch (err) { /* network */ }

Prevention

When it happens

Trigger: Calling the version diff endpoint with a from versionId that was never created, was already deleted (possibly by the retention limit), or belongs to another database/environment.

Common situations: Comparing against a version pruned by enforceRetentionLimit; stale ids in a UI dropdown after a DB switch; diffing across environments where version ids aren't shared.

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/03a0bd5dc731326a. Report an issue: GitHub.