{"record":{"id":"f9e022741de0f631","repo":"mastra-ai/mastra","slug":"agent-fs-routing-subagent-schedules-unsupported","errorCode":"AGENT_FS_ROUTING_SUBAGENT_SCHEDULES_UNSUPPORTED","errorMessage":"Agent \"${name}\": schedules are only supported on root agents, but agents/.../subagents/${name}/schedules/ declares ${schedules.length}. Move them to the root agent's schedules/ directory.","messagePattern":"Agent \"(.+?)\": schedules are only supported on root agents, but agents/\\.\\.\\./subagents/(.+?)/schedules/ declares (.+?)\\. Move them to the root agent's schedules/ directory\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/fs-routing/index.ts","lineNumber":368,"sourceCode":"  const agent = new Agent(assembled);\n  agent.__setDeclaredSchedules(resolveSchedules(name, schedules, depth));\n  return agent;\n}\n\n/**\n * Validate discovered schedules and pair each with its path-derived key.\n *\n * Only root agents may declare schedules. A schedule row targets an agent by\n * id and the worker resolves it with `mastra.getAgentById(...)`; subagents live\n * in their parent's `agents` map and are never registered on the Mastra\n * instance, so a subagent schedule would fire forever against a missing agent.\n * Failing the build is the only honest outcome.\n */\nfunction resolveSchedules(name: string, schedules: FsAgentScheduleEntry[], depth: number): DeclaredAgentSchedule[] {\n  if (schedules.length === 0) return [];\n\n  if (depth > 0) {\n    throw new MastraError({\n      id: 'AGENT_FS_ROUTING_SUBAGENT_SCHEDULES_UNSUPPORTED',\n      domain: ErrorDomain.AGENT,\n      category: ErrorCategory.USER,\n      details: { agentName: name },\n      text: `Agent \"${name}\": schedules are only supported on root agents, but agents/.../subagents/${name}/schedules/ declares ${schedules.length}. Move them to the root agent's schedules/ directory.`,\n    });\n  }\n\n  const seen = new Set<string>();\n  const resolved: DeclaredAgentSchedule[] = [];\n  for (const { key, schedule } of schedules) {\n    if (seen.has(key)) {\n      throw new MastraError({\n        id: 'AGENT_FS_ROUTING_SCHEDULE_NAME_COLLISION',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        details: { agentName: name, scheduleKey: key },\n        text: `Agent \"${name}\": duplicate schedule \"${key}\" under agents/${name}/schedules/. Two files resolve to the same schedule id; rename one.`,","sourceCodeStart":350,"sourceCodeEnd":386,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/fs-routing/index.ts#L350-L386","documentation":"resolveSchedules in fs-routing enforces that schedules may only be declared on root agents. If a subagent (depth > 0) declares a schedules/ directory with entries, the build fails with this MastraError rather than silently ignoring them.","triggerScenarios":"Creating agents/<name>/subagents/<child>/schedules/ with one or more schedule files and assembling the tree.","commonSituations":"Refactoring a root agent into a subagent and leaving its schedules/ directory in place, or copy-pasting an agent folder (including schedules/) under another agent's subagents/.","solutions":["Move the schedule files from agents/.../subagents/<name>/schedules/ to the root agent's agents/<root>/schedules/ directory.","If the child should not be scheduled at all, delete its schedules/ directory.","Restructure so the scheduled agent is a root agent if it must own its own schedules."],"exampleFix":"// before\nagents/report-agent/subagents/summarizer/schedules/nightly.ts\n// after\nagents/report-agent/schedules/nightly.ts  // moved to root agent","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nconst subagentScheduleDir = 'agents/report-agent/subagents/summarizer/schedules';\nif (existsSync(subagentScheduleDir)) {\n  throw new Error(`Schedules found on a subagent (${subagentScheduleDir}); move them to the root agent`);\n}","typeGuard":null,"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_SUBAGENT_SCHEDULES_UNSUPPORTED') {\n    logger.error(`${e.details.agentName}: relocate subagent schedules to the root agent`);\n  }\n  throw e;\n}","preventionTips":["Never copy schedules/ directories when promoting an agent to a subagent","Add a pre-commit/CI check that subagents/*/ contains no schedules directory","Document schedule placement in the agent folder template README"],"tags":["fs-routing","schedules","configuration"],"backgroundTag":"subagent-schedules-unsupported","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}