ruvnet/ruflo · error · Error

Agent not found: ${agentId}

Error message

Agent not found: ${agentId}

What it means

Plain Error thrown by LoadBalancer.getAgentLoad when agentRegistry.getAgent(agentId) returns null. The agent is not registered in the registry backing the load balancer. Note: this is NOT a ClaimOperationError, so it has no .code property; callers must match on the message text, which is more fragile than the code-based errors in claim-service.

Source

Thrown at v3/@claude-flow/claims/src/application/load-balancer.ts:367

  constructor(
    claimRepository: ILoadBalancerClaimRepository,
    agentRegistry: IAgentRegistry,
    handoffService: IHandoffService
  ) {
    super();
    this.claimRepository = claimRepository;
    this.agentRegistry = agentRegistry;
    this.handoffService = handoffService;
  }

  /**
   * Get load information for a specific agent
   */
  async getAgentLoad(agentId: string): Promise<AgentLoadInfo> {
    const agent = await this.agentRegistry.getAgent(agentId);
    if (!agent) {
      throw new Error(`Agent not found: ${agentId}`);
    }

    const claims = await this.claimRepository.getClaimsByAgent(agentId);
    const completionHistory = await this.claimRepository.getAgentCompletionHistory(agentId, 50);

    const utilization = this.calculateUtilization(claims, agent.maxClaims);
    const blockedCount = claims.filter((c) => c.status === 'blocked').length;
    const avgCompletionTime =
      completionHistory.length > 0
        ? completionHistory.reduce((sum, t) => sum + t, 0) / completionHistory.length
        : 0;

    return {
      agentId: agent.agentId,
      agentType: agent.agentType,
      claimCount: claims.length,
      maxClaims: agent.maxClaims,
      utilization,

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Register the agent in the registry before querying its load.
2. Enumerate valid ids via agentRegistry.getAgentsBySwarm(swarmId) and confirm membership.
3. Verify the agentId string exactly matches the id used at spawn time.
4. Ensure the same IAgentRegistry instance is wired into both the spawner and the LoadBalancer.

Example fix

// before
const load = await loadBalancer.getAgentLoad(agentId); // throws

// after
const agent = await agentRegistry.getAgent(agentId);
if (!agent) throw new Error(`Refusing load query: ${agentId} not registered`);
const load = await loadBalancer.getAgentLoad(agentId);

const agent = await agentRegistry.getAgent(agentId);
if (!agent) {
  throw new Error(`Agent ${agentId} is not registered`);
}
const load = await loadBalancer.getAgentLoad(agentId);

try {
  return await loadBalancer.getAgentLoad(agentId);
} catch (e) {
  // NOTE: plain Error, no .code — message matching is required and fragile
  if (e instanceof Error && /Agent not found/.test(e.message)) {
    return { notFound: true };
  }
  throw e;
}

When it happens

Trigger: Querying load for an agent id that was never spawned/registered; the agent was de-registered; using a load balancer whose agent registry belongs to a different swarm; typo in agentId.

Common situations: Agent spawned in a different process whose registry is not shared; registry not seeded at startup; agent id from a previous session that has been retired; mismatch between spawn-time id and query-time id.

Related errors

• ISSUE_NOT_FOUND
• Claim not found for issue: ${issueId}
• Claim is still in grace period
• Claim is protected by progress (${claim.progress}%)
• No steal to contest - issue was not recently stolen

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/8989656d124e94af. Report an issue: GitHub.