{"record":{"id":"0234f17fc61e03d9","repo":"mastra-ai/mastra","slug":"mode-not-found-this-id","errorCode":null,"errorMessage":"Mode not found: ${this.#id}","messagePattern":"Mode not found: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/agent-controller/session.ts","lineNumber":1687,"sourceCode":"   * the mode catalog (`config.modes`) and injects this once.\n   */\n  setResolver(resolve: (modeId: string) => AgentControllerMode | null): void {\n    this.#resolveMode = resolve;\n  }\n\n  /** The currently-selected mode id. */\n  get(): string {\n    return this.#id;\n  }\n\n  /**\n   * Resolve the currently-selected mode id to its full definition against the\n   * host's mode catalog. Throws if the selected mode id isn't in the catalog.\n   */\n  resolve(): AgentControllerMode {\n    const mode = this.#resolveMode?.(this.#id) ?? null;\n    if (!mode) {\n      throw new Error(`Mode not found: ${this.#id}`);\n    }\n    return mode;\n  }\n\n  /** Set the currently-selected mode id (on default resolution or hydration). */\n  set({ modeId }: { modeId: string }): void {\n    this.#id = modeId;\n  }\n\n  /**\n   * Switch to a different mode.\n   *\n   * Emits `mode_changed`, then runs the version-guarded sequence: remember the\n   * outgoing mode's model, persist the new mode, then resolve and apply the\n   * incoming mode's model — emitting `model_changed` once applied. A newer\n   * switch starting mid-flight supersedes this one, which then bails before\n   * emitting `model_changed`.\n   */","sourceCodeStart":1669,"sourceCodeEnd":1705,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent-controller/session.ts#L1669-L1705","documentation":"The session stores only the selected mode id; ModeState.resolve() expands it to the full mode definition using the host-provided catalog resolver. If the resolver returns nothing — the id is not in the catalog — the library throws, since downstream code needs the full definition (model, instructions) to operate.","triggerScenarios":"Calling resolve() when the persisted/selected mode id was removed from the catalog (renamed/deleted mode), the catalog failed to register modes, or hydration restored a stale id.","commonSituations":"Upgrading where a mode was renamed, switching branches/configs with different mode sets; a persisted session file referencing an old mode id; typo in a custom mode registration.","solutions":["Re-select a valid mode via ModeState.set({ modeId }) with an id from the current catalog.","Restore/rename the missing mode in the catalog so the persisted id resolves again.","Clear or migrate the persisted mode selection when the catalog changes."],"exampleFix":"// before\nconst mode = session.mode.resolve(); // throws for stale id\n// after\nconst mode = session.mode.resolve?.() ?? null;\nif (!mode) {\n  session.mode.set({ modeId: catalog.defaultModeId });\n}\nconst safeMode = session.mode.resolve();","handlingStrategy":"fallback","validationCode":"const mode = resolveMode(savedModeId);\nif (!mode) savedModeId = defaultModeId;","typeGuard":null,"tryCatchPattern":"let mode: AgentControllerMode;\ntry {\n  mode = session.mode.resolve();\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Mode not found: ')) {\n    session.mode.set({ modeId: defaultModeId });\n    mode = session.mode.resolve();\n  } else throw e;\n}","preventionTips":["Fall back to the catalog default when a saved mode id fails to resolve","Migrate persisted mode ids on upgrades/renames","List catalog modes for user selection instead of free-form ids","Register custom modes unconditionally or gate dependents with them"],"tags":["state","configuration","lifecycle"],"backgroundTag":"mode-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}