mastra-ai/mastra · error · Error

Prompt not found: ${name}

Error message

Prompt not found: ${name}

What it means

The migration prompts module (packages/mcp-docs-server) looks up a prompt by name in its static `migrationPrompts` list in getPromptMessages and throws a plain Error `Prompt not found: ${name}` when no prompt matches. This means the MCP client requested a prompt name the docs server does not offer.

Source

Thrown at packages/mcp-docs-server/src/prompts/migration.ts:40

  },
  {
    name: 'migration-checklist',
    version: 'v1',
    description:
      'Get a comprehensive checklist for migrating to Mastra v1.0. Lists all breaking changes that need to be addressed.',
  },
];

/**
 * Prompt messages callback that generates contextual migration guidance
 */
export const migrationPromptMessages: MCPServerPrompts = {
  listPrompts: async () => migrationPrompts,

  getPromptMessages: async ({ name, args }): Promise<PromptMessage[]> => {
    const prompt = migrationPrompts.find(p => p.name === name);
    if (!prompt) {
      throw new Error(`Prompt not found: ${name}`);
    }

    if (name === 'upgrade-to-v1') {
      return getUpgradeToV1Messages(args?.area);
    }

    if (name === 'migration-checklist') {
      return getMigrationChecklistMessages();
    }

    throw new Error(`No message handler for prompt: ${name}`);
  },
};

/**
 * Generate messages for the upgrade-to-v1 prompt
 */
function getUpgradeToV1Messages(area?: string): PromptMessage[] {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Call prompts/list first and use an exact name from the returned list
2. Fix the requested name to one of the available migration prompts (e.g. 'upgrade-to-v1', 'migration-checklist')
3. If you control both sides, update the client to the renamed prompt after a server version bump

Example fix

// before
await client.getPrompt({ name: 'upgrade-to-v2', args: { area: 'storage' } });
// after
const { prompts } = await client.listPrompts();
const name = prompts.find(p => p.name.startsWith('upgrade-to'))?.name;
await client.getPrompt({ name, args: { area: 'storage' } });

const available = (await client.listPrompts()).prompts.map(p => p.name);
if (!available.includes(requestedName)) {
  throw new Error(`Prompt '${requestedName}' not offered. Available: ${available.join(', ')}`);
}

function isKnownPrompt(name: string, prompts: { name: string }[]): name is string {
  return prompts.some(p => p.name === name);
}

try {
  const result = await client.getPrompt({ name, args });
} catch (e) {
  if (String(e.message).startsWith('Prompt not found')) {
    const { prompts } = await client.listPrompts();
    console.error(`Unknown prompt '${name}'. Available: ${prompts.map(p => p.name).join(', ')}`);
  } else throw e;
}

When it happens

Trigger: An MCP client calls prompts/get with a `name` that is not one of the names in `migrationPrompts` (e.g. a typo like 'upgrade-to-v2', or a prompt from a different MCP server).

Common situations: Client-side hardcoded prompt names diverging from server versions; renaming a prompt on the server while clients cache the old name; calling the migration server expecting prompts from another docs server.

Related errors

• Template "${slug}" not found. Available templates: ${templat
• Failed to fetch prompts from server ${this.client.name}: ${e
• MCP_CLIENT_GET_PROMPT_FAILED
• MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED
• App resource not found: ${uri}

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