{"record":{"id":"f8d5fdac5ce787a4","repo":"mastra-ai/mastra","slug":"agent-fs-routing-instructions-invalid","errorCode":"AGENT_FS_ROUTING_INSTRUCTIONS_INVALID","errorMessage":"Agent \"${name}\": agents/${name}/instructions.ts must default-export a string, a system message, an array of either, or a function returning one, but got ${received}.","messagePattern":"Agent \"(.+?)\": agents/(.+?)/instructions\\.ts must default-export a string, a system message, an array of either, or a function returning one, but got (.+?)\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/fs-routing/index.ts","lineNumber":487,"sourceCode":" * no default export at all never reaches here; the bundler fails first, naming\n * the same file.)\n */\nfunction assertValidInstructionsModule(\n  name: string,\n  instructions: unknown,\n): asserts instructions is DynamicArgument<AgentInstructions> {\n  const isUsable =\n    typeof instructions === 'function' ||\n    (Array.isArray(instructions)\n      ? instructions.length > 0 && instructions.every(isUsableSystemMessage)\n      : isUsableSystemMessage(instructions));\n\n  if (isUsable) {\n    return;\n  }\n\n  const received = describeInstructionsExport(instructions);\n  throw new MastraError({\n    id: 'AGENT_FS_ROUTING_INSTRUCTIONS_INVALID',\n    domain: ErrorDomain.AGENT,\n    category: ErrorCategory.USER,\n    details: { agentName: name, received },\n    text: `Agent \"${name}\": agents/${name}/instructions.ts must default-export a string, a system message, an array of either, or a function returning one, but got ${received}.`,\n  });\n}\n\n/**\n * One entry of an `AgentInstructions` value: a bare string, or a system message\n * whose `content` is a string. Anything else reaches the model as an empty\n * string, so the entries have to be checked rather than just the container —\n * `[123]` is exactly as mute as `123`.\n */\nfunction isUsableSystemMessage(value: unknown): boolean {\n  return (\n    typeof value === 'string' ||\n    (typeof value === 'object' && value !== null && typeof (value as { content?: unknown }).content === 'string')","sourceCodeStart":469,"sourceCodeEnd":505,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/fs-routing/index.ts#L469-L505","documentation":"When an Agent is defined via filesystem routing, packages/core reads agents/<name>/instructions.ts and expects its default export to be a string, a system message object, an array of those, or a function returning one of those. assertValidInstructionsModule (via resolveInstructions) inspects the runtime value of the default export and throws this error when none of the supported shapes match. It is a USER-category configuration error: the instructions file exists but its export shape is not usable.","triggerScenarios":"Creating agents/<name>/instructions.ts with `export default { instructions: '...' }` (nested object), `export default undefined`, a class instance, a Promise, or a function returning an unsupported value; forgetting the `default` keyword entirely so the module's default export is undefined; exporting a named constant instead of default-exporting it.","commonSituations":"Migrating from an older format where instructions lived in config.ts to the dedicated instructions.ts file; copy-pasting instructions into a wrapper object; TypeScript compile of the file failing so the import yields undefined; authors exporting `async function` that resolves to undefined instead of returning a string/system message.","solutions":["Make instructions.ts default-export a plain string: `export default 'You are a helpful assistant.'`","If you need rich behavior, default-export a function that returns a string, system message, or array of them (sync or async), and verify the return value with the same shape rules.","Add the missing `default` keyword if you exported a named constant (`export default instructions` instead of `export const instructions`).","Log/inspect the default export at runtime (`import mod from './instructions.ts'; console.log(describeInstructionsExport(mod))`) to see what shape the resolver actually received."],"exampleFix":"// before (agents/support/instructions.ts)\nexport const instructions = { instructions: 'You are support.' };\n\n// after\nexport default 'You are support.';","handlingStrategy":"validation","validationCode":"import mod from './agents/support/instructions.ts';\nfunction isUsableInstructions(v: unknown): boolean {\n  const isSystemMessage = (x: unknown): x is { role: string; content: string } =>\n    !!x && typeof x === 'object' && 'role' in x && 'content' in x;\n  if (typeof v === 'string' || isSystemMessage(v)) return true;\n  if (Array.isArray(v) && v.every(x => typeof x === 'string' || isSystemMessage(x))) return true;\n  if (typeof v === 'function') return true; // must return one of the above when called\n  return false;\n}\nif (!isUsableInstructions(mod)) throw new Error('instructions.ts default export shape invalid');","typeGuard":"function isSystemMessage(v: unknown): v is { role: string; content: string } {\n  return typeof v === 'object' && v !== null && 'role' in v && 'content' in v && typeof (v as any).content === 'string';\n}","tryCatchPattern":"try {\n  agent = await resolveAgentFromFs('support');\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'AGENT_FS_ROUTING_INSTRUCTIONS_INVALID') {\n    console.error('Fix agents/support/instructions.ts:', e.detail?.received);\n  } else throw e;\n}","preventionTips":["Always `export default` from instructions.ts, never a named export","Keep the default export a plain string unless you specifically need dynamic behavior","Add a unit test that imports every instructions.ts and asserts the exported shape","If using a function export, test that its return value is a string/system message/array"],"tags":["agent","filesystem-routing","instructions","config"],"backgroundTag":"invalid-default-export-shape","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}