mastra-ai/mastra · error

Mode not found: ${this.#id}

Error message

Mode not found: ${this.#id}

What it means

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.

Source

Thrown at packages/core/src/agent-controller/session.ts:1687

   * the mode catalog (`config.modes`) and injects this once.
   */
  setResolver(resolve: (modeId: string) => AgentControllerMode | null): void {
    this.#resolveMode = resolve;
  }

  /** The currently-selected mode id. */
  get(): string {
    return this.#id;
  }

  /**
   * Resolve the currently-selected mode id to its full definition against the
   * host's mode catalog. Throws if the selected mode id isn't in the catalog.
   */
  resolve(): AgentControllerMode {
    const mode = this.#resolveMode?.(this.#id) ?? null;
    if (!mode) {
      throw new Error(`Mode not found: ${this.#id}`);
    }
    return mode;
  }

  /** Set the currently-selected mode id (on default resolution or hydration). */
  set({ modeId }: { modeId: string }): void {
    this.#id = modeId;
  }

  /**
   * Switch to a different mode.
   *
   * Emits `mode_changed`, then runs the version-guarded sequence: remember the
   * outgoing mode's model, persist the new mode, then resolve and apply the
   * incoming mode's model — emitting `model_changed` once applied. A newer
   * switch starting mid-flight supersedes this one, which then bails before
   * emitting `model_changed`.
   */

View on GitHub (pinned to 75dd419e61)

Solutions

1. Re-select a valid mode via ModeState.set({ modeId }) with an id from the current catalog.
2. Restore/rename the missing mode in the catalog so the persisted id resolves again.
3. Clear or migrate the persisted mode selection when the catalog changes.

Example fix

// before
const mode = session.mode.resolve(); // throws for stale id
// after
const mode = session.mode.resolve?.() ?? null;
if (!mode) {
  session.mode.set({ modeId: catalog.defaultModeId });
}
const safeMode = session.mode.resolve();

const mode = resolveMode(savedModeId);
if (!mode) savedModeId = defaultModeId;

let mode: AgentControllerMode;
try {
  mode = session.mode.resolve();
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Mode not found: ')) {
    session.mode.set({ modeId: defaultModeId });
    mode = session.mode.resolve();
  } else throw e;
}

When it happens

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

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

Related errors

• LinearIntegration is not initialized — the factory binds sto
• No active thread on this session
• No source thread to clone
• Mode not found: ${modeId}
• Uncommitted step flow changes detected. Call .commit() to re

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