{"record":{"id":"634c3b427f21b43b","repo":"mastra-ai/mastra","slug":"server-configuration-not-found-for-name-servern","errorCode":null,"errorMessage":"Server configuration not found for name: ${serverName}","messagePattern":"Server configuration not found for name: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/configuration.ts","lineNumber":1542,"sourceCode":"  /**\n   * Gets the stderr stream of a connected stdio server.\n   *\n   * Only available for servers using stdio transport with `stderr: 'pipe'`.\n   * Returns null if the server is not connected, not using stdio, or stderr is not piped.\n   *\n   * @param serverName - The name of the server\n   * @returns The stderr stream, or null\n   */\n  public getServerStderr(serverName: string): Stream | null {\n    const client = this.mcpClientsById.get(serverName);\n    if (!client) return null;\n    return client.stderr;\n  }\n\n  private getServerConfig(serverName: string): MastraMCPServerDefinition {\n    const serverConfig = this.serverConfigs[serverName];\n    if (!serverConfig) {\n      throw new Error(`Server configuration not found for name: ${serverName}`);\n    }\n    return serverConfig;\n  }\n\n  private async getOrCreateClient(name: string, config: MastraMCPServerDefinition): Promise<InternalMastraMCPClient> {\n    if (this.disconnectPromise) {\n      await this.disconnectPromise;\n    }\n\n    const exists = this.mcpClientsById.has(name);\n    const existingClient = this.mcpClientsById.get(name);\n\n    this.logger.debug('Checking connected client', { name, exists });\n\n    if (exists) {\n      // This is just to satisfy Typescript since technically you could have this.mcpClientsById.set('someKey', undefined);\n      // Should never reach this point basically we always create a new MastraMCPClient instance when we add to the Map.\n      if (!existingClient) {","sourceCodeStart":1524,"sourceCodeEnd":1560,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/configuration.ts#L1524-L1560","documentation":"Error thrown by MCPClient's private getServerConfig when no server configuration is registered under the requested name. Many operations (getConnectedClientForServer, tools/prompts/resources access, authentication) resolve the config by name first, so an unknown name fails fast with this message.","triggerScenarios":"Passing a serverName to any MCPClient API (getConnectedClientForServer, getToolsForServer, prompts/tools/resources methods, authenticateServer) that was never registered in the constructor's serverConfigs map or via setServers.","commonSituations":"Typo in server name; environment-specific config where a server was conditionally registered; refactoring/renaming server keys; loading config from env where a variable was missing so the entry was never added.","solutions":["Check the exact serverName against the keys passed to new MCPClient({ serverConfigs: {...} }) or setServers.","Log/inspect Object.keys of the configured servers to compare at runtime.","Register the missing server configuration before calling dependent APIs.","Guard lookups with a name check before invoking client APIs when names come from dynamic input."],"exampleFix":"// before\nconst tools = await client.getToolsForServer('prod-mcp'); // typo\n// after\nconst serverName = 'prod_mcp';\nif (!(serverName in configuredServers)) throw new Error(`unknown server: ${serverName}`);\nconst tools = await client.getToolsForServer(serverName);","handlingStrategy":"validation","validationCode":"const configured = new Set(Object.keys(configuredServers));\nif (!configured.has(serverName)) {\n  throw new Error(`server \"${serverName}\" not configured. Available: ${[...configured].join(', ')}`);\n}","typeGuard":"function isConfiguredServer(name: string, configs: Record<string, MastraMCPServerDefinition>): name is keyof typeof configs & string {\n  return Object.prototype.hasOwnProperty.call(configs, name);\n}","tryCatchPattern":null,"preventionTips":["Define server names as constants/enum instead of string literals.","Log available server keys when a lookup fails.","Verify env-driven server registration actually ran (config not silently empty).","Add a startup check that every referenced server name is registered."],"tags":["mcp","configuration","lookup","naming"],"backgroundTag":"unknown-server-name","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}