mastra-ai/mastra · error · Error

Server configuration not found for name: ${serverName}

Error message

Server configuration not found for name: ${serverName}

What it means

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.

Source

Thrown at packages/mcp/src/client/configuration.ts:1542

  /**
   * Gets the stderr stream of a connected stdio server.
   *
   * Only available for servers using stdio transport with `stderr: 'pipe'`.
   * Returns null if the server is not connected, not using stdio, or stderr is not piped.
   *
   * @param serverName - The name of the server
   * @returns The stderr stream, or null
   */
  public getServerStderr(serverName: string): Stream | null {
    const client = this.mcpClientsById.get(serverName);
    if (!client) return null;
    return client.stderr;
  }

  private getServerConfig(serverName: string): MastraMCPServerDefinition {
    const serverConfig = this.serverConfigs[serverName];
    if (!serverConfig) {
      throw new Error(`Server configuration not found for name: ${serverName}`);
    }
    return serverConfig;
  }

  private async getOrCreateClient(name: string, config: MastraMCPServerDefinition): Promise<InternalMastraMCPClient> {
    if (this.disconnectPromise) {
      await this.disconnectPromise;
    }

    const exists = this.mcpClientsById.has(name);
    const existingClient = this.mcpClientsById.get(name);

    this.logger.debug('Checking connected client', { name, exists });

    if (exists) {
      // This is just to satisfy Typescript since technically you could have this.mcpClientsById.set('someKey', undefined);
      // Should never reach this point basically we always create a new MastraMCPClient instance when we add to the Map.
      if (!existingClient) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check the exact serverName against the keys passed to new MCPClient({ serverConfigs: {...} }) or setServers.
2. Log/inspect Object.keys of the configured servers to compare at runtime.
3. Register the missing server configuration before calling dependent APIs.
4. Guard lookups with a name check before invoking client APIs when names come from dynamic input.

Example fix

// before
const tools = await client.getToolsForServer('prod-mcp'); // typo
// after
const serverName = 'prod_mcp';
if (!(serverName in configuredServers)) throw new Error(`unknown server: ${serverName}`);
const tools = await client.getToolsForServer(serverName);

const configured = new Set(Object.keys(configuredServers));
if (!configured.has(serverName)) {
  throw new Error(`server "${serverName}" not configured. Available: ${[...configured].join(', ')}`);
}

function isConfiguredServer(name: string, configs: Record<string, MastraMCPServerDefinition>): name is keyof typeof configs & string {
  return Object.prototype.hasOwnProperty.call(configs, name);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot authenticate MCP server ${serverName}: it is not conf
• Cannot authenticate MCP server ${serverName}: the provider's
• MCP_SERVER_MODERN_HTTP_OPTIONS_INCOMPATIBLE
• Prompt "${name}" not found
• Agent '${agent.name}' (key: '${agentKey}') must have a non-e

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