mastra-ai/mastra · error · MastraError

AGENT_FS_ROUTING_SCHEDULE_NAME_COLLISION

AGENT_FS_ROUTING_SCHEDULE_NAME_COLLISION

Error message

Agent "${name}": duplicate schedule "${key}" under agents/${name}/schedules/. Two files resolve to the same schedule id; rename one.

What it means

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.

Source

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

 */
function resolveSchedules(name: string, schedules: FsAgentScheduleEntry[], depth: number): DeclaredAgentSchedule[] {
  if (schedules.length === 0) return [];

  if (depth > 0) {
    throw new MastraError({
      id: 'AGENT_FS_ROUTING_SUBAGENT_SCHEDULES_UNSUPPORTED',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { agentName: name },
      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.`,
    });
  }

  const seen = new Set<string>();
  const resolved: DeclaredAgentSchedule[] = [];
  for (const { key, schedule } of schedules) {
    if (seen.has(key)) {
      throw new MastraError({
        id: 'AGENT_FS_ROUTING_SCHEDULE_NAME_COLLISION',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        details: { agentName: name, scheduleKey: key },
        text: `Agent "${name}": duplicate schedule "${key}" under agents/${name}/schedules/. Two files resolve to the same schedule id; rename one.`,
      });
    }
    seen.add(key);
    assertValidScheduleDefinition(schedule, `agents/${name}/schedules/${key}`);
    resolved.push({ key, definition: schedule });
  }
  return resolved;
}

/**
 * Resolve the instructions for a file-based agent from the three sources that
 * can supply them, in this order:
 *

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
agents/my-agent/schedules/nightly.json
agents/my-agent/schedules/nightly.ts   // duplicate key "nightly"
// after
agents/my-agent/schedules/nightly.json
agents/my-agent/schedules/weekly-report.ts  // renamed

Defensive patterns

Strategy: validation

Validate before calling

import { readdirSync } from 'node:fs';
const files = readdirSync('agents/my-agent/schedules');
const keys = files.map(f => f.replace(/\.[^.]+$/, ''));
const dupes = keys.filter((k, i) => keys.indexOf(k) !== i);
if (dupes.length) throw new Error(`Duplicate schedule ids: ${dupes.join(', ')}`);

Try / catch

import { MastraError } from '@mastra/core/mastra/error';
try {
  assembleAgents(dir);
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_FS_ROUTING_SCHEDULE_NAME_COLLISION') {
    logger.error(`Duplicate schedule "${e.details.scheduleKey}" for ${e.details.agentName}; rename one file`);
  }
  throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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