{"record":{"id":"cbd3a65e5cca08c5","repo":"mastra-ai/mastra","slug":"server-configuration-must-include-either-a-command","errorCode":null,"errorMessage":"Server configuration must include either a command or a url.","messagePattern":"Server configuration must include either a command or a url\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/client.ts","lineNumber":835,"sourceCode":"  async connect() {\n    if (this.isConnected) {\n      return this.isConnected;\n    }\n\n    this.isConnected = new Promise<boolean>(async (resolve, reject) => {\n      try {\n        // A previous failed connect attempt can leave a stale transport attached\n        // to the SDK client; release it or every reconnect fails (issue #19862).\n        await this.detachStaleClientTransport();\n\n        const { command, url } = this.serverConfig;\n\n        if (command) {\n          await this.connectStdio(command);\n        } else if (url) {\n          await this.connectHttp(url);\n        } else {\n          throw new Error('Server configuration must include either a command or a url.');\n        }\n\n        this.refreshServerInstructions();\n\n        resolve(true);\n\n        // Scope the reset to this connection so an older handler retained across\n        // reconnects cannot clear the state of a replacement connection.\n        const connectedTransport = this.transport;\n        const connectionPromise = this.isConnected;\n        if (this.client.onclose !== this.clientConnectionOnClose) {\n          this.clientBaseOnClose = this.client.onclose;\n        }\n        const connectionOnClose = () => {\n          if (this.transport === connectedTransport) {\n            this.log('debug', `MCP server connection closed`);\n            // Close the stale transport before any reconnect so its EventSource/session\n            // can't keep retrying and leak server-side sessions (issue #16693). Clear","sourceCodeStart":817,"sourceCodeEnd":853,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/client.ts#L817-L853","documentation":"InternalMastraMCPClient's connection initialization requires exactly one transport: a stdio command or an HTTP url. If the resolved server configuration contains neither (and no pre-connected transport), the constructor/init path throws this error instead of attempting a connect. It is a configuration-shape guard.","triggerScenarios":"Constructing the client or registering a server whose config object omits both `command` and `url` — e.g. an empty config file entry, environment-driven config where the env var backing the url/command is unset, or a typo'd config key.","commonSituations":"MCP config JSON/YAML entry missing the url field; process.env value undefined so neither branch is taken; renaming keys in a config file; loading config where the server entry is `{ name: 'x' }` only.","solutions":["Add the required connection field to the server config: either `command` (stdio) or `url` (HTTP)","Validate the server config object before constructing the client","Check the env/config source actually resolves (typos, missing env vars)","Remove empty/dead server entries from the config"],"exampleFix":"// before\nconst client = new InternalMastraMCPClient({ name: 'weather' });\n// after\nconst client = new InternalMastraMCPClient({ name: 'weather', url: process.env.WEATHER_MCP_URL });","handlingStrategy":"validation","validationCode":"function validateServerConfig(cfg: { command?: string; url?: string }) {\n  if (!cfg.command && !cfg.url) {\n    throw new Error('Server config needs either command (stdio) or url (HTTP)');\n  }\n}\nvalidateServerConfig(serverConfig);","typeGuard":"function hasTransport(cfg: { command?: string; url?: string }): boolean {\n  return typeof cfg.command === 'string' || typeof cfg.url === 'string';\n}","tryCatchPattern":"try {\n  const client = new InternalMastraMCPClient(config);\n  await client.connect();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('must include either a command or a url')) {\n    logger.error(`Malformed MCP server config for '${config.name}': set command or url`);\n  }\n  throw e;\n}","preventionTips":["Validate server config entries at startup before constructing clients","Check that env vars backing command/url are set (print config on boot)","Keep one canonical config schema/parse step (e.g. zod) for MCP server entries","Remove empty server entries from config files"],"tags":["mcp","config","validation","client"],"backgroundTag":"missing-config-field","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}