hcengineering/platform · error

Failed to get endpoint for container ${kind}: ${err.message}

Error message

Failed to get endpoint for container ${kind}: ${err.message}

What it means

Network.getContainer asks the selected agent's api.get(kind, options) to start the container and return its [uuid, endpoint]. Any error from that remote call (agent unreachable, container image/creation failure, timeout) is wrapped in this error with the original message appended. The finally block removes the pending marker, so the failure is per-attempt.

Source

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

    const pid = ++this.pidCounter
    this.pending.set(pid, { agent: agent.id, kind, options, promise: record, clients: new Set(clients) })

    // Wait for endpoint to be established
    try {
      const recordImpl = await record

      agent.containers.add(recordImpl.record.uuid)

      this.eventQueue.push({
        agents: [],
        containers: [{ container: recordImpl.record, event: NetworkEventKind.added }]
      })

      // TODO:  What if container started with same id?
      this._containers.set(recordImpl.record.uuid, recordImpl)
      return recordImpl
    } catch (err: any) {
      throw new Error(`Failed to get endpoint for container ${kind}: ${err.message}`)
    } finally {
      this.pending.delete(pid)
    }
  }

  async release (client: ClientUuid, uuid: ContainerUuid): Promise<void> {
    const _client = this._clients.get(client)
    _client?.containers.delete(uuid)

    const existing = this._containers.get(uuid)
    if (existing !== undefined) {
      existing.clients.delete(client)
      if (existing.clients.size === 0) {
        this._orphanedContainers.set(existing.record.uuid, {
          container: existing,
          time: this.tickManager.now()
        })
      }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Read the inner err.message in the thrown text to identify the root cause (unreachable agent vs container start failure).
2. Verify the selected agent is reachable and healthy (ping its api endpoint, check its process).
3. Fix the container-side cause: image exists and pullable, runtime configured, resources/ports available.
4. Retry getContainer — the round-robin index advances so the next attempt may pick a different, healthy agent.
5. Add a fallback: try again with different options (smaller resources) or on another network/agent pool.

Example fix

// before
const rec = await network.getContainer(clientId, kind) // throws 'Failed to get endpoint...'
// after
let rec
try {
  rec = await network.getContainer(clientId, kind)
} catch (e) {
  console.error('container start failed:', e.message)
  rec = await network.getContainer(clientId, kind) // retry, may pick another agent
}

// Pre-check agent health before scheduling:
for (const a of network.agents?.values?.() ?? []) {
  if (!a.kinds.includes(kind)) continue
  const healthy = await pingAgent(a) // e.g. api.ping with timeout
  if (healthy) { /* proceed */ }
}

function isEndpointAllocated(r: { record?: { uuid?: string; endpoint?: string } }): boolean {
  return typeof r.record?.uuid === 'string' && typeof r.record.endpoint === 'string'
}

for (let attempt = 0; attempt < 3; attempt++) {
  try {
    return await network.getContainer(clientId, kind, options)
  } catch (e) {
    if (!(e as Error).message.startsWith('Failed to get endpoint')) throw e
    console.warn(`container start attempt ${attempt + 1} failed: ${e.message}`)
    await sleep(2 ** attempt * 500) // backoff; round-robin may pick another agent
  }
}
throw new Error(`could not start container ${kind} after retries`)

When it happens

Trigger: The chosen agent's api.get throws — network partition to the agent, agent crashed mid-call, container runtime failure to start the image, endpoint allocation failure, or timeout while awaiting the endpoint.

Common situations: Agent host down or DNS/ports blocked; container registry auth failure or missing image; resource exhaustion on the agent node (OOM, no free ports); transient timeout under load that a retry would clear.

Related errors

• Invalid endpoint reference
• No connection available
• Agent endpoint not initialized after server start

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