{"record":{"id":"d40de38547bf54bc","repo":"mastra-ai/mastra","slug":"no-message-handler-for-prompt-name","errorCode":null,"errorMessage":"No message handler for prompt: ${name}","messagePattern":"No message handler for prompt: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp-docs-server/src/prompts/migration.ts","lineNumber":51,"sourceCode":" */\nexport const migrationPromptMessages: MCPServerPrompts = {\n  listPrompts: async () => migrationPrompts,\n\n  getPromptMessages: async ({ name, args }): Promise<PromptMessage[]> => {\n    const prompt = migrationPrompts.find(p => p.name === name);\n    if (!prompt) {\n      throw new Error(`Prompt not found: ${name}`);\n    }\n\n    if (name === 'upgrade-to-v1') {\n      return getUpgradeToV1Messages(args?.area);\n    }\n\n    if (name === 'migration-checklist') {\n      return getMigrationChecklistMessages();\n    }\n\n    throw new Error(`No message handler for prompt: ${name}`);\n  },\n};\n\n/**\n * Generate messages for the upgrade-to-v1 prompt\n */\nfunction getUpgradeToV1Messages(area?: string): PromptMessage[] {\n  if (area) {\n    return [\n      {\n        role: 'user',\n        content: {\n          type: 'text',\n          text: `I need help migrating my Mastra ${area} code from v0.x to v1.0. Use the mastraMigration tool to:\n\n1. If packages aren't already at the 'latest' tag, upgrade packages to the 'latest' tag and do an install of the new packages.\n2. First, try to get the specific migration guide for \"${area}\" using path: \"upgrade-to-v1/${area}\"\n3. If that doesn't exist, try the alternate form (singular/plural):","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp-docs-server/src/prompts/migration.ts#L33-L69","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a dispatch branch in getPromptMessages for the unhandled prompt name returning its PromptMessage[]","Remove the prompt from `migrationPrompts` if it should not be offered","Write a test iterating every listed prompt name through getPromptMessages to catch missing handlers"],"exampleFix":"// before\nif (name === 'migration-checklist') {\n  return getMigrationChecklistMessages();\n}\nthrow new Error(`No message handler for prompt: ${name}`);\n// after\nif (name === 'migration-checklist') {\n  return getMigrationChecklistMessages();\n}\nif (name === 'new-migration-guide') {\n  return getNewMigrationGuideMessages();\n}\nthrow new Error(`No message handler for prompt: ${name}`);","handlingStrategy":"try-catch","validationCode":"for (const p of migrationPrompts) {\n  // fail fast at startup if any listed prompt lacks a handler\n  if (!handledPromptNames.has(p.name)) throw new Error(`Prompt '${p.name}' listed but no message handler`);\n}","typeGuard":"function hasHandler(name: string, handlers: Record<string, unknown>): name is keyof typeof handlers {\n  return Object.prototype.hasOwnProperty.call(handlers, name);\n}","tryCatchPattern":"try {\n  const messages = await getPromptMessages({ name, args });\n} catch (e) {\n  if (String(e.message).startsWith('No message handler for prompt')) {\n    console.error(`Server bug: prompt '${name}' advertised without a handler branch`);\n  } else throw e;\n}","preventionTips":["Drive handlers from a single registry map (name -> handler) instead of if-branches so the list and handlers cannot diverge","Add a test that calls getPromptMessages for every prompt returned by listPrompts","When adding a prompt, update both migrationPrompts and the dispatch logic in the same PR"],"tags":["mcp","prompts","missing-handler","internal-consistency"],"backgroundTag":"prompt-handler-missing","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}