hcengineering/platform · error

No suitable agents found for container ${kind}

Error message

No suitable agents found for container ${kind}

What it means

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.

Source

Thrown at foundations/net/packages/core/src/network.ts:381

            (p.options.labels !== undefined && options.labels.every((l) => (p.options.labels ?? []).includes(l))))
        ) {
          // Add to pendings list to properly track orphaned
          for (const cl of clients) {
            p.clients.add(cl)
          }
          const containerImpl = await p.promise
          for (const cl of clients) {
            containerImpl.clients.add(cl)
          }
          return containerImpl
        }
      }
    }

    // Select agent using round/robin and register it in agent
    const suitableAgents = Array.from(this._agents.values().filter((it) => it.kinds.includes(kind)))
    if (suitableAgents.length === 0) {
      throw new Error(`No suitable agents found for container ${kind}`)
    }
    const agent = Array.from(suitableAgents)[++this.idx % suitableAgents.length]

    const record: Promise<ContainerRecordImpl> = agent.api.get(kind, options).then(([uuid, endpoint]) => ({
      agent,
      record: {
        uuid,
        agentId: agent.api.uuid,
        kind,
        lastVisit: this.tickManager.now(),
        endpoint: '' as ContainerEndpointRef, // Placeholder, will be updated later
        labels: options.labels,
        extra: options.extra
      },
      clients: new Set(clients),
      endpoint
    }))

View on GitHub (pinned to 63e28dc964)

Solutions

  1. Verify the kind string matches exactly what agents advertise in their kinds list.
  2. Start/connect at least one agent that supports the kind and confirm it registered with the network (check agent join logs).
  3. Inspect network._agents to see which kinds are currently available; fix agent registration/kind advertisement if missing.
  4. If agents register asynchronously, wait for their join/advertise event before requesting containers of that kind.

Example fix

// before
await network.getContainer(clientId, 'gpu-worker') // no agent advertises 'gpu-worker'
// after
await network.registerAgent(gpuAgentRecord, gpuAgent) // agent with kinds: ['gpu-worker']
await network.getContainer(clientId, 'gpu-worker')
Defensive patterns

Strategy: validation

Validate before calling

const available = [...network.agents?.values?.() ?? []].flatMap(a => a.kinds)
if (!available.includes(kind)) {
  throw new Error(`kind "${kind}" is not served by any connected agent; available: ${available.join(', ')}`)
}
// only then:
await network.getContainer(clientId, kind, options)

Type guard

function kindSupported(kind: string, agents: { kinds: string[] }[]): boolean {
  return agents.some(a => a.kinds.includes(kind))
}

Try / catch

try {
  return await network.getContainer(clientId, kind, options)
} catch (e) {
  if ((e as Error).message.includes('No suitable agents found')) {
    await waitForAgentWithKind(network, kind, { timeoutMs: 30000 }) // wait/retry until an agent advertises the kind
    return await network.getContainer(clientId, kind, options)
  }
  throw e
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/7916a18648aa63de. Report an issue: GitHub.