mastra-ai/mastra · error · MastraError

AGENT_FS_ROUTING_SUBAGENT_NAME_COLLISION

AGENT_FS_ROUTING_SUBAGENT_NAME_COLLISION

Error message

Agent "${name}": duplicate subagent "${childId}" under agents/${name}/subagents/.

What it means

During filesystem-based agent assembly, mergeSubAgents collects subagents from agents/<name>/subagents/ and builds a keyed record. If two subagent directories resolve to the same agent id (childEntry.name), the second insertion is detected as a duplicate and this error is thrown. Duplicate ids are ambiguous for routing/selection, so the library fails fast instead of silently shadowing one subagent.

Source

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

  if (typeof configAgents === 'function') {
    if (fsSubAgents.length > 0) {
      onWarn(
        `Agent "${name}": config.agents is a function, so discovered subagents under agents/${name}/subagents/ are ignored.`,
      );
    }
    return configAgents;
  }

  const fromConfig = (configAgents ?? {}) as Record<string, Agent>;
  const configKeys = new Set(Object.keys(fromConfig));
  const toolKeys = new Set(Object.keys(mergedTools ?? {}));

  const fromFs: Record<string, Agent> = {};
  for (const childEntry of fsSubAgents) {
    const childId = childEntry.name;

    if (childId in fromFs) {
      throw new MastraError({
        id: 'AGENT_FS_ROUTING_SUBAGENT_NAME_COLLISION',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        details: { agentName: name, subagentName: childId },
        text: `Agent "${name}": duplicate subagent "${childId}" under agents/${name}/subagents/.`,
      });
    }

    if (toolKeys.has(childId)) {
      throw new MastraError({
        id: 'AGENT_FS_ROUTING_SUBAGENT_NAME_COLLISION',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        details: { agentName: name, subagentName: childId },
        text: `Agent "${name}": subagent "${childId}" collides with a tool of the same name. Rename agents/${name}/subagents/${childId}/ or the tool.`,
      });
    }

View on GitHub (pinned to 75dd419e61)

Solutions

Open each agents/<name>/subagents/<child>/config.ts and give every subagent a unique `name` (the collision id is in the error details: subagentName).
Rename or remove one of the duplicate directories if it is an accidental copy.
Check for symlinks or duplicate directory entries (including case-only differences) that make the same subagent appear twice.

Example fix

// before (agents/main/subagents/researcher-copy/config.ts)
export const config = { name: 'researcher', /* ... */ };

// after
export const config = { name: 'researcher-copy', /* ... */ };

Defensive patterns

Strategy: validation

Validate before calling

import { readdirSync, readFileSync } from 'node:fs';
const dirs = readdirSync('./agents/main/subagents', { withFileTypes: true }).filter(d => d.isDirectory());
const names = dirs.map(d => {
  const cfg = readFileSync(`./agents/main/subagents/${d.name}/config.ts`, 'utf8');
  return /name:\s*['"]([^'"]+)['"]/.exec(cfg)?.[1];
});
const dupes = names.filter((n, i) => n && names.indexOf(n) !== i);
if (dupes.length) throw new Error(`Duplicate subagent names: ${dupes}`);

Try / catch

try {
  buildAgentFromFs('main');
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_FS_ROUTING_SUBAGENT_NAME_COLLISION') {
    console.error('Subagent name collision:', e.detail?.subagentName);
  } else throw e;
}

Prevention

When copying a subagent directory, immediately change the `name` in the copied config.ts
Keep directory names and config `name` identical to avoid confusion
CI lint: assert subagent names across all agents are unique
Avoid case-only directory name differences

When it happens

Trigger: Two directories under agents/<name>/subagents/ whose config.ts declare the same agent name/id; a subagent whose constructed Agent .name matches another entry; case-insensitive filesystems where 'Research/' and 'research/' directories coexist and both normalize to the same id.

Common situations: Copying an existing subagent directory to tweak it but forgetting to change the `name` in the new config.ts; symlinking a shared subagent under two paths; renaming a directory on disk without updating the agent name inside config.ts.

Related errors

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