mastra-ai/mastra · error · MastraError

AGENT_FS_ROUTING_MODEL_REQUIRED

AGENT_FS_ROUTING_MODEL_REQUIRED

Error message

Agent "${name}": missing model in config.ts and no default. Provide a 'model' in agents/${name}/config.ts.

What it means

File-system agent routing assembles agents from agents/<name>/ directories. After merging config.ts values, assembleAtDepth requires a `model` — either defined in config.ts or supplied as an assembly default. If both are absent it throws this MastraError (ErrorCategory.USER).

Source

Thrown at packages/core/src/agent/fs-routing/index.ts:317

    }
    return config;
  }

  // Presence is the key being set, not the value being defined: codegen emits
  // `instructions` only when the file exists, so a module that default-exports
  // `undefined` has to read as a broken file rather than as no file at all.
  // Own key only: an inherited one never came from a discovered file.
  const instructions = resolveInstructions(
    name,
    config.instructions,
    instructionsModule,
    Object.hasOwn(entry, 'instructions'),
    instructionsMd,
    onWarn,
  );

  if (!config.model) {
    throw new MastraError({
      id: 'AGENT_FS_ROUTING_MODEL_REQUIRED',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { agentName: name },
      text: `Agent "${name}": missing model in config.ts and no default. Provide a 'model' in agents/${name}/config.ts.`,
    });
  }

  const mergedTools = mergeTools(name, tools, config.tools, onWarn);
  const mergedSkills = mergeSkills(name, skills, config.skills, onWarn);
  const mergedWorkspace = mergeWorkspace(name, workspace, config, defaultWorkspaceBasePath, onWarn);
  const mergedMemory = mergeMemory(name, memory, config.memory, onWarn);
  const mergedAgents = mergeSubAgents(name, subagents, config.agents, mergedTools, depth, options);
  const mergedInputProcessors = mergeProcessors(name, 'input', inputProcessors, config.inputProcessors, onWarn);
  const mergedOutputProcessors = mergeProcessors(name, 'output', outputProcessors, config.outputProcessors, onWarn);
  const mergedScorers = mergeScorers(name, scorers, config.scorers, onWarn);

  const assembled = {

View on GitHub (pinned to 75dd419e61)

Solutions

Add a `model` field to agents/<name>/config.ts.
Or pass a default model to the fs-routing assembler so all agents inherit it.
Check config.ts for typos (e.g. `models` vs `model`) or a failing import that made the field undefined.

Example fix

// agents/my-agent/config.ts — before
export const config = { instructions: 'You are helpful' };
// after
import { openai } from '@ai-sdk/openai';
export const config = { instructions: 'You are helpful', model: openai('gpt-4o') };

Defensive patterns

Strategy: validation

Validate before calling

import { config } from './agents/my-agent/config';
if (!('model' in config) || !config.model) {
  throw new Error('agents/my-agent/config.ts must export a non-empty `model`');
}

Type guard

interface AgentConfig { model?: unknown; instructions?: string }
function hasModel(c: AgentConfig): c is AgentConfig & { model: unknown } {
  return !!c.model;
}

Try / catch

import { MastraError } from '@mastra/core/mastra/error';
try {
  assembleAgents(dir);
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_FS_ROUTING_MODEL_REQUIRED') {
    logger.error(`${e.details.agentName}: add a model to config.ts`);
  }
  throw e;
}

Prevention

Scaffold new agents from a template that includes model in config.ts
Add a CI lint that every agents/*/config.ts exports a `model`
Watch for typos (`models`, `modelConfig`) and failed imports silently undefined-ing the field
Pass an explicit default model when assembling if agents may omit it

When it happens

Trigger: Building/serving an fs-routed agent whose agents/<name>/config.ts exports no `model` field and no default model was passed to the assembler.

Common situations: Newly scaffolded agent folders with only instructions.md, renaming a model constant out of config.ts, or upgrading to fs-routing from programmatic agents without porting the model config.

Related errors

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