mastra-ai/mastra · error · HTTPException

Version with id ${versionId} not found

Error message

Version with id ${versionId} not found

What it means

This 404 is thrown when mcpClientStore.getVersion(versionId) returns null, meaning no stored version exists with that id. The endpoint treats a missing version as 404 for the version resource.

Source

Thrown at packages/server/src/server/handlers/mcp-client-versions.ts:196

  description: 'Returns a specific version of an MCP client by its version ID',
  tags: ['MCP Client Versions'],
  handler: async ({ mastra, mcpClientId, versionId, requestContext }) => {
    try {
      const storage = mastra.getStorage();

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

      const mcpClientStore = await storage.getStore('mcpClients');
      if (!mcpClientStore) {
        throw new HTTPException(500, { message: 'MCP clients storage domain is not available' });
      }

      const version = await mcpClientStore.getVersion(versionId);

      if (!version) {
        throw new HTTPException(404, { message: `Version with id ${versionId} not found` });
      }

      if (version.mcpClientId !== mcpClientId) {
        throw new HTTPException(404, {
          message: `Version with id ${versionId} not found for MCP client ${mcpClientId}`,
        });
      }
      const mcpClient = await mcpClientStore.getById(mcpClientId);
      assertStoredResourceScope(mcpClient, await getStoredResourceScope(mastra, requestContext));

      return version;
    } catch (error) {
      return handleError(error, 'Error getting MCP client version');
    }
  },
});

/**

View on GitHub (pinned to 75dd419e61)

Solutions

1. List the versions for the MCP client first and use an id from that list
2. Check that retention settings did not prune the version
3. Verify the versionId against the storage backend directly
4. Correct any typo in the path parameter

Example fix

// before
await fetch(`/api/mcp-clients/${clientId}/versions/${'v_bad'}`)
// after
const versions = await fetch(`/api/mcp-clients/${clientId}/versions`).then(r => r.json());
await fetch(`/api/mcp-clients/${clientId}/versions/${versions[0].id}`)

const versions = await fetch(`/api/mcp-clients/${clientId}/versions`).then(r => r.json());
if (!versions.some(v => v.id === versionId)) throw new Error(`Version ${versionId} does not exist for client ${clientId}`);

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

try {
  const res = await fetch(`/api/mcp-clients/${clientId}/versions/${versionId}`);
  if (res.status === 404) {
    // refresh version list; the version may have been pruned
    return null;
  }
  return await res.json();
} catch (err) {
  // handle network/other failures
}

When it happens

Trigger: Calling GET an MCP client version endpoint with a versionId that does not exist in storage (already pruned by retention, never created, or mistyped).

Common situations: A retention limit job deleted old versions the caller still references; the caller uses a version id from another MCP client or environment; ids copied from logs that were truncated.

Related errors

• MCP client with id ${mcpClientId} not found
• Prompt block with id ${promptBlockId} not found
• Stored agent with id ${storedAgentId} not found
• Stored MCP client with id ${storedMCPClientId} not found
• Stored scorer definition with id ${storedScorerId} not found

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