mastra-ai/mastra · error · MastraError

AGENT_FS_ROUTING_SUBAGENT_SCHEDULES_UNSUPPORTED

AGENT_FS_ROUTING_SUBAGENT_SCHEDULES_UNSUPPORTED

Error message

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.

What it means

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.

Source

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

  const agent = new Agent(assembled);
  agent.__setDeclaredSchedules(resolveSchedules(name, schedules, depth));
  return agent;
}

/**
 * Validate discovered schedules and pair each with its path-derived key.
 *
 * Only root agents may declare schedules. A schedule row targets an agent by
 * id and the worker resolves it with `mastra.getAgentById(...)`; subagents live
 * in their parent's `agents` map and are never registered on the Mastra
 * instance, so a subagent schedule would fire forever against a missing agent.
 * Failing the build is the only honest outcome.
 */
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.`,

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Move the schedule files from agents/.../subagents/<name>/schedules/ to the root agent's agents/<root>/schedules/ directory.
  2. If the child should not be scheduled at all, delete its schedules/ directory.
  3. Restructure so the scheduled agent is a root agent if it must own its own schedules.

Example fix

// before
agents/report-agent/subagents/summarizer/schedules/nightly.ts
// after
agents/report-agent/schedules/nightly.ts  // moved to root agent
Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
const subagentScheduleDir = 'agents/report-agent/subagents/summarizer/schedules';
if (existsSync(subagentScheduleDir)) {
  throw new Error(`Schedules found on a subagent (${subagentScheduleDir}); move them to the root agent`);
}

Try / catch

import { MastraError } from '@mastra/core/mastra/error';
try {
  assembleAgents(dir);
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_FS_ROUTING_SUBAGENT_SCHEDULES_UNSUPPORTED') {
    logger.error(`${e.details.agentName}: relocate subagent schedules to the root agent`);
  }
  throw e;
}

Prevention

When it happens

Trigger: Creating agents/<name>/subagents/<child>/schedules/ with one or more schedule files and assembling the tree.

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

Related errors

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