hcengineering/platform · error

Invalid endpoint reference

Error message

Invalid endpoint reference

What it means

establishConnection parses the container's endpoint reference to decide direct vs routed connectivity. If the parsed ref has no uuid, the endpoint string is malformed or is a placeholder, so no valid connection can be built and it throws 'Invalid endpoint reference'. Called by conn/connect/handleRefUpdate/handleNewContainer.

Source

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

    // TODO: Wait for all pending requests to finish

    if (request.uuid !== undefined) {
      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) {

View on GitHub (pinned to 63e28dc964)

Solutions

1. Wait for the container's endpoint ref update before connecting (subscribe to ref update events)
2. Validate the endpoint ref with parseEndpointRef before calling connect
3. Re-request the endpoint via container.endpoint / handleNewContainer to get a fresh ref
4. Check that the agent published the container endpoint correctly

Example fix

// before
const conn = client.conn(uuid) // may throw on bad ref
// after
const ref = client.getEndpointRef?.(uuid)
const parsed = ref !== undefined ? parseEndpointRef(ref) : undefined
if (parsed?.uuid !== undefined) {
  const conn = client.conn(uuid)
} else {
  await waitForRefUpdate(uuid)
}

const parsed = parseEndpointRef(endpoint)
if (parsed.uuid === undefined) {
  await waitForRefUpdate(uuid)
}

function isConnectableRef(endpoint: ContainerEndpointRef): boolean {
  const p = parseEndpointRef(endpoint)
  return p.uuid !== undefined && p.kind !== EndpointKind.noconnect
}

try {
  const conn = client.establishConnection(uuid, endpoint)
} catch (e) {
  if (e instanceof Error && e.message === 'Invalid endpoint reference') {
    await waitForRefUpdate(uuid)
  } else { throw e }
}

When it happens

Trigger: Calling client.connect/conn for a container whose endpoint ref string doesn't parse into a form carrying a uuid — e.g. an unassigned, malformed, or placeholder endpoint produced before the container published a real endpoint.

Common situations: Connecting immediately after container creation before the endpoint ref update arrives; corrupted/older endpoint refs from a stale registry; handling a ref update whose payload isn't a valid endpoint.

Related errors

• No connection available
• Unable to determine the required version of Rush from ${RUSH
• Invalid package specifier: ${rawPackageSpecifier}
• platform.status.ConnectionClosed
• Failed to parse response for part ${partNumber}

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