{"record":{"id":"8989656d124e94af","repo":"ruvnet/ruflo","slug":"agent-not-found-agentid","errorCode":null,"errorMessage":"Agent not found: ${agentId}","messagePattern":"Agent not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/claims/src/application/load-balancer.ts","lineNumber":367,"sourceCode":"\n  constructor(\n    claimRepository: ILoadBalancerClaimRepository,\n    agentRegistry: IAgentRegistry,\n    handoffService: IHandoffService\n  ) {\n    super();\n    this.claimRepository = claimRepository;\n    this.agentRegistry = agentRegistry;\n    this.handoffService = handoffService;\n  }\n\n  /**\n   * Get load information for a specific agent\n   */\n  async getAgentLoad(agentId: string): Promise<AgentLoadInfo> {\n    const agent = await this.agentRegistry.getAgent(agentId);\n    if (!agent) {\n      throw new Error(`Agent not found: ${agentId}`);\n    }\n\n    const claims = await this.claimRepository.getClaimsByAgent(agentId);\n    const completionHistory = await this.claimRepository.getAgentCompletionHistory(agentId, 50);\n\n    const utilization = this.calculateUtilization(claims, agent.maxClaims);\n    const blockedCount = claims.filter((c) => c.status === 'blocked').length;\n    const avgCompletionTime =\n      completionHistory.length > 0\n        ? completionHistory.reduce((sum, t) => sum + t, 0) / completionHistory.length\n        : 0;\n\n    return {\n      agentId: agent.agentId,\n      agentType: agent.agentType,\n      claimCount: claims.length,\n      maxClaims: agent.maxClaims,\n      utilization,","sourceCodeStart":349,"sourceCodeEnd":385,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/claims/src/application/load-balancer.ts#L349-L385","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register the agent in the registry before querying its load.","Enumerate valid ids via agentRegistry.getAgentsBySwarm(swarmId) and confirm membership.","Verify the agentId string exactly matches the id used at spawn time.","Ensure the same IAgentRegistry instance is wired into both the spawner and the LoadBalancer."],"exampleFix":"// before\nconst load = await loadBalancer.getAgentLoad(agentId); // throws\n\n// after\nconst agent = await agentRegistry.getAgent(agentId);\nif (!agent) throw new Error(`Refusing load query: ${agentId} not registered`);\nconst load = await loadBalancer.getAgentLoad(agentId);","handlingStrategy":"validation","validationCode":"const agent = await agentRegistry.getAgent(agentId);\nif (!agent) {\n  throw new Error(`Agent ${agentId} is not registered`);\n}\nconst load = await loadBalancer.getAgentLoad(agentId);","typeGuard":null,"tryCatchPattern":"try {\n  return await loadBalancer.getAgentLoad(agentId);\n} catch (e) {\n  // NOTE: plain Error, no .code — message matching is required and fragile\n  if (e instanceof Error && /Agent not found/.test(e.message)) {\n    return { notFound: true };\n  }\n  throw e;\n}","preventionTips":["Register agents in the registry before querying load.","Enumerate valid ids via getAgentsBySwarm and pass only those to getAgentLoad.","Wire the same IAgentRegistry instance into the spawner and the LoadBalancer."],"tags":["load-balancer","agent-registry","not-found","plain-error"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}