{"record":{"id":"dbf1f6f776dfd220","repo":"mastra-ai/mastra","slug":"agent-fs-routing-instructions-required","errorCode":"AGENT_FS_ROUTING_INSTRUCTIONS_REQUIRED","errorMessage":"Agent \"${name}\": missing instructions. Provide agents/${name}/instructions.md, agents/${name}/instructions.ts, or an 'instructions' field in config.ts.","messagePattern":"Agent \"(.+?)\": missing instructions\\. Provide agents/(.+?)/instructions\\.md, agents/(.+?)/instructions\\.ts, or an 'instructions' field in config\\.ts\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/fs-routing/index.ts","lineNumber":452,"sourceCode":"  if (hasModule) {\n    assertValidInstructionsModule(name, instructionsModule);\n    if (hasMd) {\n      onWarn(\n        `Agent \"${name}\": instructions defined in both instructions.ts and instructions.md; instructions.ts wins.`,\n      );\n    }\n    return instructionsModule;\n  }\n\n  if (hasMd) {\n    return instructionsMd as AgentInstructions;\n  }\n\n  if (hasConfigInstructions) {\n    return configInstructions;\n  }\n\n  throw new MastraError({\n    id: 'AGENT_FS_ROUTING_INSTRUCTIONS_REQUIRED',\n    domain: ErrorDomain.AGENT,\n    category: ErrorCategory.USER,\n    details: { agentName: name },\n    text: `Agent \"${name}\": missing instructions. Provide agents/${name}/instructions.md, agents/${name}/instructions.ts, or an 'instructions' field in config.ts.`,\n  });\n}\n\n/**\n * Reject an `instructions.ts` whose default export isn't a usable instructions\n * value. Anything outside the `AgentInstructions` shapes is silently coerced to\n * an empty prompt downstream, so without this an author who exported the wrong\n * thing gets a mute agent and no clue which file caused it — the error has to\n * name the file while assembly still knows it. `null` and `undefined` are\n * rejected the same way rather than reading as \"no file here\" — the caller\n * decides presence from the file existing, not from the value. (A module with\n * no default export at all never reaches here; the bundler fails first, naming\n * the same file.)","sourceCodeStart":434,"sourceCodeEnd":470,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/fs-routing/index.ts#L434-L470","documentation":"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).","triggerScenarios":"Assembling an fs-routed agent whose directory lacks instructions.md/instructions.ts and whose config.ts exports no `instructions` field.","commonSituations":"Freshly scaffolded agent folders, renaming instructions.md, a typo like `instruction` in config.ts, or a failed instructions.ts import yielding undefined.","solutions":["Add agents/<name>/instructions.md with the agent's system instructions.","Or export an `instructions` field from agents/<name>/config.ts.","Or create instructions.ts exporting the instructions string (check it has a valid default/named export).","Check spelling/case of the filename (Instructions.md will not resolve)."],"exampleFix":"// before\n// agents/my-agent/config.ts\nexport const config = { model: openai('gpt-4o') };\n// after\nexport const config = { model: openai('gpt-4o'), instructions: 'You are a helpful assistant.' };\n// or add agents/my-agent/instructions.md","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nfor (const dir of ['agents/my-agent']) {\n  const hasMd = existsSync(`${dir}/instructions.md`);\n  const hasTs = existsSync(`${dir}/instructions.ts`);\n  const cfg = existsSync(`${dir}/config.ts`) && !!(await import(`./${dir}/config.ts`)).config?.instructions;\n  if (!hasMd && !hasTs && !cfg) throw new Error(`${dir}: no instructions found`);\n}","typeGuard":"function hasInstructions(c: { instructions?: unknown }): c is { instructions: string } {\n  return typeof c.instructions === 'string' && c.instructions.trim().length > 0;\n}","tryCatchPattern":"import { MastraError } from '@mastra/core/mastra/error';\ntry {\n  assembleAgents(dir);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'AGENT_FS_ROUTING_INSTRUCTIONS_REQUIRED') {\n    logger.error(`${e.details.agentName}: add instructions.md / instructions.ts / config.instructions`);\n  }\n  throw e;\n}","preventionTips":["Scaffold agents from a template that always includes instructions.md","Add a CI lint asserting every agents/*/ directory has instructions via one of the three supported sources","Check spelling and casing of instructions files after refactors","Validate instructions.ts exports resolve to a non-empty string at build time"],"tags":["fs-routing","configuration","instructions"],"backgroundTag":"missing-agent-instructions","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}