{"record":{"id":"7916a18648aa63de","repo":"hcengineering/platform","slug":"no-suitable-agents-found-for-container-kind","errorCode":null,"errorMessage":"No suitable agents found for container ${kind}","messagePattern":"No suitable agents found for container (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"foundations/net/packages/core/src/network.ts","lineNumber":381,"sourceCode":"            (p.options.labels !== undefined && options.labels.every((l) => (p.options.labels ?? []).includes(l))))\n        ) {\n          // Add to pendings list to properly track orphaned\n          for (const cl of clients) {\n            p.clients.add(cl)\n          }\n          const containerImpl = await p.promise\n          for (const cl of clients) {\n            containerImpl.clients.add(cl)\n          }\n          return containerImpl\n        }\n      }\n    }\n\n    // Select agent using round/robin and register it in agent\n    const suitableAgents = Array.from(this._agents.values().filter((it) => it.kinds.includes(kind)))\n    if (suitableAgents.length === 0) {\n      throw new Error(`No suitable agents found for container ${kind}`)\n    }\n    const agent = Array.from(suitableAgents)[++this.idx % suitableAgents.length]\n\n    const record: Promise<ContainerRecordImpl> = agent.api.get(kind, options).then(([uuid, endpoint]) => ({\n      agent,\n      record: {\n        uuid,\n        agentId: agent.api.uuid,\n        kind,\n        lastVisit: this.tickManager.now(),\n        endpoint: '' as ContainerEndpointRef, // Placeholder, will be updated later\n        labels: options.labels,\n        extra: options.extra\n      },\n      clients: new Set(clients),\n      endpoint\n    }))\n","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/net/packages/core/src/network.ts#L363-L399","documentation":"Network.getContainer schedules a new container of the requested kind by filtering registered agents whose `kinds` include that kind and picking one round-robin. If no registered agent advertises the kind, there is nowhere to start the container, so the network throws. This is a scheduling/capability failure, not a transport failure.","triggerScenarios":"Calling getContainer (via record/client acquisition) with kind K while this._agents contains no agent whose kinds array includes K — e.g. zero agents connected, or all connected agents advertise only other kinds.","commonSituations":"Typo in the kind string ('worker' vs 'workers'); agents failed to join the network or advertise kinds after a restart; deploying an agent image that dropped support for the kind; network started before any agent registered.","solutions":["Verify the kind string matches exactly what agents advertise in their kinds list.","Start/connect at least one agent that supports the kind and confirm it registered with the network (check agent join logs).","Inspect network._agents to see which kinds are currently available; fix agent registration/kind advertisement if missing.","If agents register asynchronously, wait for their join/advertise event before requesting containers of that kind."],"exampleFix":"// before\nawait network.getContainer(clientId, 'gpu-worker') // no agent advertises 'gpu-worker'\n// after\nawait network.registerAgent(gpuAgentRecord, gpuAgent) // agent with kinds: ['gpu-worker']\nawait network.getContainer(clientId, 'gpu-worker')","handlingStrategy":"validation","validationCode":"const available = [...network.agents?.values?.() ?? []].flatMap(a => a.kinds)\nif (!available.includes(kind)) {\n  throw new Error(`kind \"${kind}\" is not served by any connected agent; available: ${available.join(', ')}`)\n}\n// only then:\nawait network.getContainer(clientId, kind, options)","typeGuard":"function kindSupported(kind: string, agents: { kinds: string[] }[]): boolean {\n  return agents.some(a => a.kinds.includes(kind))\n}","tryCatchPattern":"try {\n  return await network.getContainer(clientId, kind, options)\n} catch (e) {\n  if ((e as Error).message.includes('No suitable agents found')) {\n    await waitForAgentWithKind(network, kind, { timeoutMs: 30000 }) // wait/retry until an agent advertises the kind\n    return await network.getContainer(clientId, kind, options)\n  }\n  throw e\n}","preventionTips":["Centralize kind names in a shared constants module to avoid typos.","Gate container requests on agent join/advertisement events.","Health-check agent connectivity before scheduling work.","Monitor advertised kinds in metrics and alert when a required kind drops to zero agents."],"tags":["scheduling","capacity","agent-discovery","container"],"backgroundTag":"no-suitable-agent","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}