{"record":{"id":"d5cba8ddf78ce700","repo":"mastra-ai/mastra","slug":"mode-mode-id-requires-a-defaultmodelid-when-no","errorCode":null,"errorMessage":"Mode ${mode.id} requires a defaultModelId when no backing agent is configured","messagePattern":"Mode (.+?) requires a defaultModelId when no backing agent is configured","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/agent-controller/agent-controller.ts","lineNumber":1436,"sourceCode":"    if (mode.agent) {\n      if (!this.#legacyAgentMode[mode.id]) {\n        this.#legacyAgentMode[mode.id] = mode.agent;\n      }\n      return this.#legacyAgentMode[mode.id]!;\n    }\n\n    // Shared backing agent — reuse the single instance.\n    // The harness never mutates the agent's own instructions or tools.\n    // Mode instructions are passed at call time via buildAgentMessageStreamOptions;\n    // mode tools are resolved at execution time via buildToolsets.\n    if (this.config.agent) {\n      return this.config.agent;\n    }\n\n    // No backing agent — construct one per mode (cached).\n    if (!this.#legacyAgentMode[mode.id]) {\n      if (!mode.defaultModelId) {\n        throw new Error(`Mode ${mode.id} requires a defaultModelId when no backing agent is configured`);\n      }\n\n      const instructions = [this.#instructions ?? '', mode.instructions].filter(Boolean).join('\\n');\n      const modeTools = {\n        ...mode.tools,\n        ...mode.additionalTools,\n      };\n\n      // Model resolution flows through the gateways registered on the internal\n      // Mastra instance: the bare model id string is handed to the Agent, and\n      // `propagateRuntimeServicesToAgent` attaches the internal Mastra so the\n      // model router resolves it via the configured gateways (auth included).\n      const model = mode.defaultModelId;\n      this.#legacyAgentMode[mode.id] = new Agent({\n        id: `${this.id}-agent`,\n        name: `Harness ${this.id} agent`,\n        model,\n        instructions,","sourceCodeStart":1418,"sourceCodeEnd":1454,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent-controller/agent-controller.ts#L1418-L1454","documentation":"When the controller has no backing agent in config, it constructs a per-mode agent on demand; that requires the mode to declare a defaultModelId so the agent has a model. A mode without defaultModelId and without a backing agent is an invalid configuration, so construction fails fast.","triggerScenarios":"Calling getAgentForMode (directly or via stream/generate paths) with a mode that has no config.agent and no mode.defaultModelId set.","commonSituations":"Registering a custom mode object and forgetting defaultModelId; refactoring from a backed-agent setup to mode-based setup; copying mode definitions across projects where the agent was previously supplied.","solutions":["Set defaultModelId on the mode definition (use a literal model name/id, e.g. 'openai/gpt-4o')","Or provide config.agent so the mode does not need to construct its own agent","Validate mode configs at startup to catch missing defaultModelId before a request triggers it"],"exampleFix":"// before\nconst mode = { id: 'research', instructions: '...' };\n// after\nconst mode = { id: 'research', instructions: '...', defaultModelId: 'openai/gpt-4o' };","handlingStrategy":"validation","validationCode":"if (!controller.config.agent && !mode.defaultModelId) {\n  throw new Error(`Mode ${mode.id} is misconfigured: needs defaultModelId or a backing agent`);\n}","typeGuard":"function isRunnableMode(mode): mode is typeof mode & { defaultModelId: string } {\n  return typeof mode.defaultModelId === 'string' && mode.defaultModelId.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Validate all mode definitions at startup with a schema (zod/valibot)","Use literal model ids in configs; avoid placeholders","Keep mode definitions co-located with a type that requires defaultModelId when agent is absent"],"tags":["configuration","agent","model"],"backgroundTag":"missing-required-config","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}