mastra-ai/mastra · error · Error

No message handler for prompt: ${name}

Error message

No message handler for prompt: ${name}

What it means

In the migration prompts handler, a prompt name can pass the lookup in `migrationPrompts` but fall through all message-handler branches (`upgrade-to-v1`, `migration-checklist`), triggering `No message handler for prompt: ${name}`. This indicates an internal inconsistency: a prompt is advertised in the list but has no getPromptMessages implementation branch.

Source

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

 */
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[] {
  if (area) {
    return [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `I need help migrating my Mastra ${area} code from v0.x to v1.0. Use the mastraMigration tool to:

1. If packages aren't already at the 'latest' tag, upgrade packages to the 'latest' tag and do an install of the new packages.
2. First, try to get the specific migration guide for "${area}" using path: "upgrade-to-v1/${area}"
3. If that doesn't exist, try the alternate form (singular/plural):

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add a dispatch branch in getPromptMessages for the unhandled prompt name returning its PromptMessage[]
2. Remove the prompt from `migrationPrompts` if it should not be offered
3. Write a test iterating every listed prompt name through getPromptMessages to catch missing handlers

Example fix

// before
if (name === 'migration-checklist') {
  return getMigrationChecklistMessages();
}
throw new Error(`No message handler for prompt: ${name}`);
// after
if (name === 'migration-checklist') {
  return getMigrationChecklistMessages();
}
if (name === 'new-migration-guide') {
  return getNewMigrationGuideMessages();
}
throw new Error(`No message handler for prompt: ${name}`);

for (const p of migrationPrompts) {
  // fail fast at startup if any listed prompt lacks a handler
  if (!handledPromptNames.has(p.name)) throw new Error(`Prompt '${p.name}' listed but no message handler`);
}

function hasHandler(name: string, handlers: Record<string, unknown>): name is keyof typeof handlers {
  return Object.prototype.hasOwnProperty.call(handlers, name);
}

try {
  const messages = await getPromptMessages({ name, args });
} catch (e) {
  if (String(e.message).startsWith('No message handler for prompt')) {
    console.error(`Server bug: prompt '${name}' advertised without a handler branch`);
  } else throw e;
}

When it happens

Trigger: Requesting messages for a prompt that exists in `migrationPrompts` but is not handled by the if-branches in getPromptMessages — i.e. a prompt added to the list without adding a handler branch, or a handler branch deleted/renamed.

Common situations: Contributing a new migration prompt to the list and forgetting the dispatch branch; refactoring handler functions and dropping a case; version skew where a client knows a newer prompt name than the deployed server handler supports.

Related errors

• Failed to fetch prompts from server ${this.client.name}: ${e
• MCP_CLIENT_GET_PROMPT_FAILED
• MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED
• Failed to load prompts
• MCP_SERVER_RESOURCES_NOT_CONFIGURED

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