{"record":{"id":"fbfb9cd8db0a5b78","repo":"mastra-ai/mastra","slug":"default-mode-not-found-config-defaultmodeid","errorCode":null,"errorMessage":"Default mode not found: ${config.defaultModeId}","messagePattern":"Default mode not found: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/agent-controller/agent-controller.ts","lineNumber":272,"sourceCode":"    validateModes(config.modes);\n\n    this.id = config.id;\n    this.config = config;\n    this.#instructions = config.instructions;\n    if (config.channels) {\n      this.#channels = new AgentControllerChannels(config.channels);\n      this.#channels.__setController(this);\n    }\n    // Gateway manager merges configured gateways with the router defaults\n    // (custom takes precedence). Shared by listAvailableModels,\n    // getCurrentModelAuthStatus, and the OM model resolver.\n    this.#gatewayManager = new GatewayManager([...(config.gateways ?? []), ...defaultGateways]);\n\n    const defaultMode = config.defaultModeId\n      ? config.modes.find(mode => mode.id === config.defaultModeId)\n      : (config.modes.find(mode => mode.default || mode.metadata?.default === true) ?? config.modes[0]);\n    if (!defaultMode) {\n      throw new Error(\n        config.defaultModeId\n          ? `Default mode not found: ${config.defaultModeId}`\n          : 'AgentController requires at least one agent mode',\n      );\n    }\n\n    this.#defaultMode = defaultMode;\n\n    this.workspace = config.workspace;\n    this.browser = config.browser;\n  }\n\n  /**\n   * Subscribe to process-local notifications for newly materialized sessions.\n   * Cached `createSession()` calls do not notify listeners again.\n   *\n   * Async listeners are fire-and-forget by default. Pass `blocking: true` to\n   * make `createSession()` await the listener before resolving — for setup that","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent-controller/agent-controller.ts#L254-L290","documentation":"At construction, AgentController resolves a default mode: explicitly via config.defaultModeId, or implicitly via mode.default/metadata.default, falling back to modes[0]. If defaultModeId is set but no mode with that id exists, it throws 'Default mode not found' (the sibling message covers an entirely empty modes array).","triggerScenarios":"new AgentController({ modes: [{id:'a'},{id:'b'}], defaultModeId: 'chat' }) where no mode has id 'chat' — from renamed modes, stale config, or env-driven default ids that don't match registered modes.","commonSituations":"Environment variable (e.g. DEFAULT_MODE) whose value was never registered as a mode; renaming a mode id without updating defaultModeId; copy-pasting controller configs across projects with different mode sets.","solutions":["Set defaultModeId to an existing mode id from the modes array","Add a mode with the configured defaultModeId","Make defaultModeId configuration-driven with a validation step against available mode ids before constructing"],"exampleFix":"// before\nnew AgentController({ modes: [{ id: 'chat' }], defaultModeId: 'agent' })\n// after\nnew AgentController({ modes: [{ id: 'chat' }], defaultModeId: 'chat' })","handlingStrategy":"validation","validationCode":"const modeIds = new Set(config.modes.map(m => m.id));\nif (config.defaultModeId && !modeIds.has(config.defaultModeId)) {\n  throw new Error(`defaultModeId \"${config.defaultModeId}\" is not a registered mode`);\n}\nif (config.modes.length === 0) throw new Error('AgentController requires at least one mode');","typeGuard":null,"tryCatchPattern":"try {\n  new AgentController(config);\n} catch (e) {\n  if ((e as Error).message.startsWith('Default mode not found')) {\n    // correct defaultModeId from env/config to a registered mode id\n  }\n}","preventionTips":["Derive defaultModeId from a constant shared with mode definitions","Validate env-provided default mode values against registered ids at startup","Never hardcode defaultModeId strings copied from other projects"],"tags":["configuration","agent-controller","default-mode","startup"],"backgroundTag":"invalid-default-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}