{"record":{"id":"a02e8857cd745673","repo":"mastra-ai/mastra","slug":"agent-fs-routing-schedule-name-collision","errorCode":"AGENT_FS_ROUTING_SCHEDULE_NAME_COLLISION","errorMessage":"Agent \"${name}\": duplicate schedule \"${key}\" under agents/${name}/schedules/. Two files resolve to the same schedule id; rename one.","messagePattern":"Agent \"(.+?)\": duplicate schedule \"(.+?)\" under agents/(.+?)/schedules/\\. Two files resolve to the same schedule id; rename one\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/fs-routing/index.ts","lineNumber":381,"sourceCode":" */\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.`,\n      });\n    }\n    seen.add(key);\n    assertValidScheduleDefinition(schedule, `agents/${name}/schedules/${key}`);\n    resolved.push({ key, definition: schedule });\n  }\n  return resolved;\n}\n\n/**\n * Resolve the instructions for a file-based agent from the three sources that\n * can supply them, in this order:\n *","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/fs-routing/index.ts#L363-L399","documentation":"resolveSchedules detects duplicate schedule ids: two files under agents/<name>/schedules/ whose resolved keys collide. Since schedule ids must be unique per agent, the second file triggers this MastraError listing the colliding key.","triggerScenarios":"Having two schedule files in the same agent's schedules/ directory that resolve to the same key — e.g. nightly.json and nightly.ts, or two files whose exported id/filename both normalize to the same schedule id.","commonSituations":"Adding a TS schedule alongside an older JSON one without deleting the old file, case-insensitive filesystems colliding Nightly.ts/nightly.ts, or duplicated files from a copy-paste/merge.","solutions":["Rename one of the colliding files (or its exported schedule id) so keys are unique.","Delete the stale duplicate left over from a refactor or merge.","List the schedules/ directory to spot same-name files with different extensions."],"exampleFix":"// before\nagents/my-agent/schedules/nightly.json\nagents/my-agent/schedules/nightly.ts   // duplicate key \"nightly\"\n// after\nagents/my-agent/schedules/nightly.json\nagents/my-agent/schedules/weekly-report.ts  // renamed","handlingStrategy":"validation","validationCode":"import { readdirSync } from 'node:fs';\nconst files = readdirSync('agents/my-agent/schedules');\nconst keys = files.map(f => f.replace(/\\.[^.]+$/, ''));\nconst dupes = keys.filter((k, i) => keys.indexOf(k) !== i);\nif (dupes.length) throw new Error(`Duplicate schedule ids: ${dupes.join(', ')}`);","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_SCHEDULE_NAME_COLLISION') {\n    logger.error(`Duplicate schedule \"${e.details.scheduleKey}\" for ${e.details.agentName}; rename one file`);\n  }\n  throw e;\n}","preventionTips":["Use one extension convention (e.g. only .ts) for schedule files to avoid basename collisions","Grep schedules/ directories after merges for same-basename files","Add a CI check that resolves schedule keys and asserts uniqueness before build"],"tags":["fs-routing","schedules","duplicate-key"],"backgroundTag":"duplicate-schedule-id","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}