hcengineering/platform · error

No connection available

Error message

No connection available

What it means

After parsing, establishConnection inspects the endpoint kind. If it is EndpointKind.noconnect, the container explicitly published that no connection is currently possible (e.g. it is stopping, stateless, or not accepting connections), so the client refuses to establish and throws 'No connection available'.

Source

Thrown at foundations/net/packages/client/src/client.ts:347

      const existing = this.references.get(request.uuid)
      if (existing !== undefined) {
        return existing.ref
      }
    }
    const [uuid, endpoint] = await this.retryGetContainerRef(kind, request)
    const ref: ContainerReference = new ContainerReferenceImpl(uuid, this)
    this.references.set(uuid, { kind, ref, request, endpoint })
    return ref
  }

  establishConnection (uuid: ContainerUuid, endpoint: ContainerEndpointRef): ContainerConnectionImpl {
    // Check if connection is routed
    const parsedRef = parseEndpointRef(endpoint)
    if (parsedRef.uuid === undefined) {
      throw new Error('Invalid endpoint reference')
    }
    if (parsedRef.kind === EndpointKind.noconnect) {
      throw new Error('No connection available')
    }
    if (parsedRef.kind === EndpointKind.routed) {
      const agentRef = agentDirectRef(parsedRef.host, parsedRef.port, parsedRef.agentId)
      let agentConn = this.agentConnections.get(agentRef)
      if (agentConn === undefined) {
        agentConn = new RoutedNetworkAgentConnectionImpl<ClientUuid>(
          this.tickMgr,
          this.clientId,
          parsedRef.host,
          parsedRef.port
        )
        this.agentConnections.set(agentRef, agentConn)
      }
      let conn = this.containerConnections.get(uuid)
      if (conn === undefined) {
        conn = new ContainerConnectionImpl(uuid, agentConn.connect(parsedRef.uuid))
      } else {
        conn.setConnection(agentConn.connect(parsedRef.uuid))

View on GitHub (pinned to 63e28dc964)

Solutions

1. Wait for a connectable endpoint ref (non-noconnect) before connecting, e.g. via ref update events
2. Retry with backoff if the container is expected to become ready
3. Check container state first; skip connecting to stopping containers
4. Use the routed/agent path if the container publishes one instead of failing fast

Example fix

// before
const conn = client.conn(uuid)
// after
async function connectWhenReady(uuid: ContainerUuid) {
  for (;;) {
    try { return client.conn(uuid) } catch { await sleep(500) }
  }
}

const parsed = parseEndpointRef(endpoint)
if (parsed.kind === EndpointKind.noconnect) {
  await waitForRefUpdate(uuid) // don't attempt connect yet
}

function isConnectable(endpoint: ContainerEndpointRef): boolean {
  return parseEndpointRef(endpoint).kind !== EndpointKind.noconnect
}

for (let attempt = 0; attempt < 5; attempt++) {
  try { return client.conn(uuid) }
  catch (e) {
    if (e instanceof Error && e.message === 'No connection available') {
      await sleep(500 * 2 ** attempt); continue
    }
    throw e
  }
}

When it happens

Trigger: Connecting to a container whose latest endpoint ref is of kind noconnect — containers that are terminating, not yet ready, or intentionally non-connectable.

Common situations: Connect attempts racing with container shutdown; containers whose first published ref is noconnect before they become ready; retry loops hammering a stopping container.

Related errors

• Invalid endpoint reference
• rate-limit
• platform.status.ConnectionClosed
• Agent endpoint not initialized after server start
• Failed to get endpoint for container ${kind}: ${err.message}

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