ruvnet/ruflo · error · Error

Agent with name '${input.name}' already exists

Error message

Agent with name '${input.name}' already exists

What it means

SpawnAgentCommandHandler enforces name uniqueness: repository.findByName(input.name) must return nothing before Agent.create() runs. An existing agent with the same name aborts the spawn — agent names act as a natural key in the repository.

Source

Thrown at v3/@claude-flow/swarm/src/application/commands/spawn-agent.command.ts:46

 */
export interface SpawnAgentResult {
  success: boolean;
  agentId: string;
  agent: Agent;
  startedAutomatically: boolean;
}

/**
 * Spawn Agent Command Handler
 */
export class SpawnAgentCommandHandler {
  constructor(private readonly repository: IAgentRepository) {}

  async execute(input: SpawnAgentInput): Promise<SpawnAgentResult> {
    // Check if agent with same name exists
    const existing = await this.repository.findByName(input.name);
    if (existing) {
      throw new Error(`Agent with name '${input.name}' already exists`);
    }

    // Create agent
    const agent = Agent.create({
      name: input.name,
      role: input.role,
      domain: input.domain,
      capabilities: input.capabilities,
      parentId: input.parentId,
      metadata: input.metadata,
      maxConcurrentTasks: input.maxConcurrentTasks,
    });

    // Auto-start if requested
    let startedAutomatically = false;
    if (input.autoStart) {
      agent.start();
      startedAutomatically = true;

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Generate unique names per spawn: append a uuid or counter (worker-${crypto.randomUUID().slice(0, 8)}).
2. Check findByName first and reuse the existing agent instead of spawning a duplicate.
3. Terminate the old agent before re-spawning the same name.
4. Reset the agent repository between dev/test runs.

Example fix

// before
await spawnAgent.execute({ name: 'worker-1', role: 'coder' }); // second run throws

// after — unique name per spawn, or reuse the existing agent
const existing = await agentRepository.findByName('worker-1');
if (existing) {
  return existing;
}
await spawnAgent.execute({ name: `worker-${crypto.randomUUID().slice(0, 8)}`, role: 'coder' });

const existing = await agentRepository.findByName(input.name);
if (existing) {
  return existing; // reuse instead of spawn
}
await spawnAgentHandler.execute(input);

try {
  await spawnAgentHandler.execute(input);
} catch (e) {
  if (e instanceof Error && /already exists$/.test(e.message)) {
    const dup = await agentRepository.findByName(input.name);
    // reuse dup, or retry with a suffixed unique name
  } else {
    throw e;
  }
}

When it happens

Trigger: Re-running a spawn script without terminating the previous agents; hardcoded names like 'worker-1' colliding across runs or teams; an agent from a previous session still registered because the repository was not cleared; concurrent spawns racing on the same name.

Common situations: Bootstrap/provision scripts executed twice; an autoscaler restarting agents while old ones remain registered; dev and test sharing a persistent agent repository.

Related errors

• Can only resume paused agent
• task step ${step.stepId} requires config.agentId or workflow
• agent_execute failed
• ruflo proxy supervisor failed to spawn — no PID returned
• duplicate declared build input

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/3565bddcfb6f9898. Report an issue: GitHub.