mastra-ai/mastra · error · MastraError

AGENT_FS_ROUTING_INSTRUCTIONS_REQUIRED

AGENT_FS_ROUTING_INSTRUCTIONS_REQUIRED

Error message

Agent "${name}": missing instructions. Provide agents/${name}/instructions.md, agents/${name}/instructions.ts, or an 'instructions' field in config.ts.

What it means

resolveInstructions in fs-routing requires every assembled agent to have instructions. It checks instructions.md, instructions.ts, and an `instructions` field in config.ts; if none is present it throws this MastraError (ErrorCategory.USER).

Source

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

  if (hasModule) {
    assertValidInstructionsModule(name, instructionsModule);
    if (hasMd) {
      onWarn(
        `Agent "${name}": instructions defined in both instructions.ts and instructions.md; instructions.ts wins.`,
      );
    }
    return instructionsModule;
  }

  if (hasMd) {
    return instructionsMd as AgentInstructions;
  }

  if (hasConfigInstructions) {
    return configInstructions;
  }

  throw new MastraError({
    id: 'AGENT_FS_ROUTING_INSTRUCTIONS_REQUIRED',
    domain: ErrorDomain.AGENT,
    category: ErrorCategory.USER,
    details: { agentName: name },
    text: `Agent "${name}": missing instructions. Provide agents/${name}/instructions.md, agents/${name}/instructions.ts, or an 'instructions' field in config.ts.`,
  });
}

/**
 * Reject an `instructions.ts` whose default export isn't a usable instructions
 * value. Anything outside the `AgentInstructions` shapes is silently coerced to
 * an empty prompt downstream, so without this an author who exported the wrong
 * thing gets a mute agent and no clue which file caused it — the error has to
 * name the file while assembly still knows it. `null` and `undefined` are
 * rejected the same way rather than reading as "no file here" — the caller
 * decides presence from the file existing, not from the value. (A module with
 * no default export at all never reaches here; the bundler fails first, naming
 * the same file.)

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add agents/<name>/instructions.md with the agent's system instructions.
2. Or export an `instructions` field from agents/<name>/config.ts.
3. Or create instructions.ts exporting the instructions string (check it has a valid default/named export).
4. Check spelling/case of the filename (Instructions.md will not resolve).

Example fix

// before
// agents/my-agent/config.ts
export const config = { model: openai('gpt-4o') };
// after
export const config = { model: openai('gpt-4o'), instructions: 'You are a helpful assistant.' };
// or add agents/my-agent/instructions.md

import { existsSync } from 'node:fs';
for (const dir of ['agents/my-agent']) {
  const hasMd = existsSync(`${dir}/instructions.md`);
  const hasTs = existsSync(`${dir}/instructions.ts`);
  const cfg = existsSync(`${dir}/config.ts`) && !!(await import(`./${dir}/config.ts`)).config?.instructions;
  if (!hasMd && !hasTs && !cfg) throw new Error(`${dir}: no instructions found`);
}

function hasInstructions(c: { instructions?: unknown }): c is { instructions: string } {
  return typeof c.instructions === 'string' && c.instructions.trim().length > 0;
}

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

When it happens

Trigger: Assembling an fs-routed agent whose directory lacks instructions.md/instructions.ts and whose config.ts exports no `instructions` field.

Common situations: Freshly scaffolded agent folders, renaming instructions.md, a typo like `instruction` in config.ts, or a failed instructions.ts import yielding undefined.

Related errors

• AGENT_FS_ROUTING_MODEL_REQUIRED
• AGENT_FS_ROUTING_SUBAGENT_SCHEDULES_UNSUPPORTED
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Auth0 domain and audience are required, please provide them

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