ruvnet/ruflo · error · Error

Agent '${input.agentId}' not found

Error message

Agent '${input.agentId}' not found

What it means

TerminateAgentCommandHandler resolves the agent with repository.findById(input.agentId); when no agent exists it throws before agent.terminate() or save() runs. Standard entity-not-found guard — terminate ids must reference agents currently registered in the repository.

Source

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

/**
 * Terminate Agent Command Result
 */
export interface TerminateAgentResult {
  success: boolean;
  agentId: string;
  tasksReassigned: number;
}

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

  async execute(input: TerminateAgentInput): Promise<TerminateAgentResult> {
    const agent = await this.repository.findById(input.agentId);
    if (!agent) {
      throw new Error(`Agent '${input.agentId}' not found`);
    }

    const currentTasks = agent.currentTaskCount;

    if (currentTasks > 0 && !input.force) {
      throw new Error(`Agent has ${currentTasks} active tasks. Use force=true to terminate anyway.`);
    }

    agent.terminate();
    await this.repository.save(agent);

    return {
      success: true,
      agentId: input.agentId,
      tasksReassigned: currentTasks,
    };
  }
}

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Confirm the id via repository.findById or the agent listing before terminating.
2. Treat not-found as success in cleanup paths (idempotent termination).
3. Refresh ids from the authoritative agent registry before acting.

Example fix

// before
await terminateAgent.execute({ agentId }); // throws on unknown id

// after — idempotent cleanup
if (await agentRepository.findById(agentId)) {
  await terminateAgent.execute({ agentId });
}

if (!(await agentRepository.findById(agentId))) {
  return; // already terminated/removed: nothing to do
}
await terminateAgentHandler.execute({ agentId });

try {
  await terminateAgentHandler.execute({ agentId });
} catch (e) {
  if (e instanceof Error && /^Agent '.*' not found$/.test(e.message)) {
    return; // idempotent termination
  }
  throw e;
}

When it happens

Trigger: Terminating an already-terminated agent whose record was removed; a mistyped or truncated id; an in-memory repository reset between spawn and terminate; concurrent cleanup loops where another worker terminated the agent first.

Common situations: Stale UI state after a refresh; shutdown/cleanup scripts racing each other; restart losing in-memory registrations; ids copy-pasted from logs of a previous run.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Agent not found: ${agentId}
• Agent has ${currentTasks} active tasks. Use force=true to te
• hexToBytes: odd-length hex string
• SSRF guard: only HTTPS URLs are permitted, got ${parsed.prot
• SSRF guard: private/loopback host rejected — ${host}

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