{"record":{"id":"1668025b9ecb30d2","repo":"mastra-ai/mastra","slug":"mode-mode-id-transitionsto-references-unknown","errorCode":null,"errorMessage":"Mode \"${mode.id}\" transitionsTo references unknown mode \"${mode.transitionsTo}\"","messagePattern":"Mode \"(.+?)\" transitionsTo references unknown mode \"(.+?)\"","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/agent-controller/agent-controller.ts","lineNumber":84,"sourceCode":"      throw new Error(`Duplicate mode id \"${mode.id}\" found when creating the AgentController`);\n    }\n\n    modeIds.add(mode.id);\n\n    const modeRecord = mode as unknown as { id: string; tools?: unknown; additionalTools?: unknown };\n    if (modeRecord.tools && modeRecord.additionalTools) {\n      throw new Error(\n        `Mode \"${modeRecord.id}\" cannot set both \"tools\" and \"additionalTools\" - choose replace OR augment`,\n      );\n    }\n  }\n\n  for (const mode of modes) {\n    if (mode.transitionsTo === mode.id) {\n      throw new Error(`Mode \"${mode.id}\" transitionsTo cannot reference itself`);\n    }\n    if (mode.transitionsTo && !modeIds.has(mode.transitionsTo)) {\n      throw new Error(`Mode \"${mode.id}\" transitionsTo references unknown mode \"${mode.transitionsTo}\"`);\n    }\n  }\n}\n\n/**\n * Build a user-facing message for a non-success stream finish reason.\n *\n * Anthropic's classifier blocks / model refusals (e.g. `claude-fable-5`) surface\n * through the AI SDK as a `content-filter` finish reason, with details on\n * `providerMetadata.anthropic.stopDetails`. Without explicit handling these\n * runs end on an empty assistant message with no error, so the run appears to\n * silently stop. Returning a message here lets the controller finalize the run\n * into an explicit terminal error state.\n */\n/**\n * The Anthropic model that `claude-fable-5` runs are automatically retried on\n * server-side when fable-5's safety classifiers block a turn. See\n * {@link buildFableFallbackProviderOptions}.","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent-controller/agent-controller.ts#L66-L102","documentation":"validateModes checks that every mode's transitionsTo target exists among the declared mode ids. If a mode references a mode id that was never registered, the controller would be unable to transition, so construction fails with this error naming both the referencing mode and the unknown target.","triggerScenarios":"new AgentController({ modes: [...] }) where mode 'plan' has transitionsTo: 'execute' but no mode with id 'execute' exists — due to typos, removed modes, or case-sensitive id mismatches.","commonSituations":"Deleting or renaming a mode without updating other modes' transitionsTo; typos in mode ids ('Execute' vs 'execute'); conditional config assembly that drops a mode other modes still reference.","solutions":["Add the missing mode with the referenced id to the modes array","Fix the transitionsTo value to match an existing mode id exactly (case-sensitive)","Grep the config for all transitionsTo values and verify each exists in modes"],"exampleFix":"// before\nmodes: [{ id: 'plan', transitionsTo: 'execute' }]\n// after\nmodes: [{ id: 'plan', transitionsTo: 'execute' }, { id: 'execute' }]","handlingStrategy":"validation","validationCode":"function assertTransitionsResolve(modes: { id: string; transitionsTo?: string }[]): void {\n  const ids = new Set(modes.map(m => m.id));\n  for (const m of modes) {\n    if (m.transitionsTo && !ids.has(m.transitionsTo))\n      throw new Error(`Mode \"${m.id}\" references unknown mode \"${m.transitionsTo}\"`);\n  }\n}\nassertTransitionsResolve(config.modes);","typeGuard":null,"tryCatchPattern":"try {\n  new AgentController(config);\n} catch (e) {\n  if ((e as Error).message.includes('references unknown mode')) {\n    // add the missing mode or correct the transitionsTo id\n  }\n}","preventionTips":["After renaming/removing a mode, grep all transitionsTo references","Validate the transitions graph at config-load time","Use typed mode-id unions so TypeScript catches unknown targets"],"tags":["configuration","agent-controller","state-machine","missing-reference"],"backgroundTag":"dangling-reference-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}