{"record":{"id":"eec4b8e3762228c4","repo":"mastra-ai/mastra","slug":"mastracode-requires-at-least-one-mode","errorCode":null,"errorMessage":"MastraCode requires at least one mode","messagePattern":"MastraCode requires at least one mode","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/index.ts","lineNumber":1059,"sourceCode":"    ? undefined\n    : selectPreferredOMPack(startupAccess, activeProviderId)?.modelId;\n  const effectiveObserverModel = resolveOmRoleModel(globalSettings, 'observer', builtinOmPacks) || preferredOmModel;\n  const effectiveReflectorModel = resolveOmRoleModel(globalSettings, 'reflector', builtinOmPacks) || preferredOmModel;\n  const effectiveObservationThreshold = globalSettings.models.omObservationThreshold ?? undefined;\n  const effectiveReflectionThreshold = globalSettings.models.omReflectionThreshold ?? undefined;\n  const effectiveCavemanObservations = globalSettings.models.omCavemanObservations ?? undefined;\n  const effectiveObserveAttachments = globalSettings.models.omObserveAttachments ?? 'auto';\n\n  const modes = addPluginToolsToModeAllowlists(\n    applyEffectiveDefaultsToModes(config?.modes ? config.modes : defaultModes, effectiveDefaults),\n    Object.keys(pluginTools),\n  );\n  const defaultModeId =\n    modes.find(mode => mode.metadata?.default === true)?.id ??\n    modes.find(mode => mode.id === 'build')?.id ??\n    modes[0]?.id;\n  if (!defaultModeId) {\n    throw new Error('MastraCode requires at least one mode');\n  }\n\n  // Map subagent types to mode models: explore→fast, plan→plan, execute→build\n  // const subagentModeMap: Record<string, string> = { explore: 'fast', plan: 'plan', execute: 'build' };\n  // Subagents inherit workspace tools from the parent agent's workspace automatically.\n  // Apply disabledTools filter to both default and custom subagents.\n  // const subagents = [];\n\n  // Build initial state with global preferences. OM knobs are skipped when the\n  // host persists memory settings elsewhere (`disableSettingsOmSeed`) so the\n  // machine-local settings.json never leaks into server sessions.\n  const globalInitialState: Partial<MastraCodeState> = {};\n  if (!config?.disableSettingsOmSeed) {\n    if (effectiveObserverModel) {\n      globalInitialState.observerModelId = effectiveObserverModel;\n    }\n    if (effectiveReflectorModel) {\n      globalInitialState.reflectorModelId = effectiveReflectorModel;","sourceCodeStart":1041,"sourceCodeEnd":1077,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/index.ts#L1041-L1077","documentation":"createMastraCodeAgentController() derives defaultModeId by finding a mode with metadata.default === true, then the 'build' mode, then modes[0]. If the modes array is empty, all lookups yield undefined and the controller throws, since MastraCode cannot operate without at least one agent mode.","triggerScenarios":"Constructing the controller with a modes configuration that resolves to an empty array — e.g. all modes filtered out by feature flags/disabledTools config, a custom modes loader returning [], or misconfigured modes config paths yielding no entries.","commonSituations":"Custom setups that override modes but forget to include a default/'build' mode; config-driven mode gating that excludes everything in a minimal environment; typos in mode registration that silently skip all modes.","solutions":["Ensure at least one mode is registered, ideally one with metadata: { default: true } or id: 'build'.","Log the resolved modes array before creating the controller to find what filtered them all out.","If building modes dynamically, fall back to including the built-in 'build' mode when the list is empty."],"exampleFix":"// before\nconst modes = enabledModes.filter(m => flags[m.id]); // can be []\n// after\nconst resolved = enabledModes.filter(m => flags[m.id]);\nconst modes = resolved.length > 0 ? resolved : [buildMode];","handlingStrategy":"validation","validationCode":"const hasDefault = modes.some(m => m.metadata?.default === true || m.id === 'build');\nif (!Array.isArray(modes) || modes.length === 0) {\n  throw new Error('modes config resolved to an empty list; register at least one mode');\n}","typeGuard":"function hasAtLeastOneMode(ms: unknown): ms is NonEmptyArray<MastraCodeMode> {\n  return Array.isArray(ms) && ms.length > 0;\n}","tryCatchPattern":"try {\n  controller = await createMastraCodeAgentController({ ...cfg, modes });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('requires at least one mode')) {\n    controller = await createMastraCodeAgentController({ ...cfg, modes: [defaultBuildMode] });\n  } else { throw err; }\n}","preventionTips":["Always register a mode with metadata.default: true (or id 'build') as a baseline.","Log the modes array after dynamic filtering to catch empty results early.","Make mode filters additive rather than subtractive so a bad flag can't remove all modes."],"tags":["configuration","modes","startup"],"backgroundTag":"no-modes-configured","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}