{"record":{"id":"f8c3f5b2918ece8d","repo":"hcengineering/platform","slug":"invalid-endpoint-reference","errorCode":null,"errorMessage":"Invalid endpoint reference","messagePattern":"Invalid endpoint reference","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"foundations/net/packages/client/src/client.ts","lineNumber":344,"sourceCode":"    // TODO: Wait for all pending requests to finish\n\n    if (request.uuid !== undefined) {\n      const existing = this.references.get(request.uuid)\n      if (existing !== undefined) {\n        return existing.ref\n      }\n    }\n    const [uuid, endpoint] = await this.retryGetContainerRef(kind, request)\n    const ref: ContainerReference = new ContainerReferenceImpl(uuid, this)\n    this.references.set(uuid, { kind, ref, request, endpoint })\n    return ref\n  }\n\n  establishConnection (uuid: ContainerUuid, endpoint: ContainerEndpointRef): ContainerConnectionImpl {\n    // Check if connection is routed\n    const parsedRef = parseEndpointRef(endpoint)\n    if (parsedRef.uuid === undefined) {\n      throw new Error('Invalid endpoint reference')\n    }\n    if (parsedRef.kind === EndpointKind.noconnect) {\n      throw new Error('No connection available')\n    }\n    if (parsedRef.kind === EndpointKind.routed) {\n      const agentRef = agentDirectRef(parsedRef.host, parsedRef.port, parsedRef.agentId)\n      let agentConn = this.agentConnections.get(agentRef)\n      if (agentConn === undefined) {\n        agentConn = new RoutedNetworkAgentConnectionImpl<ClientUuid>(\n          this.tickMgr,\n          this.clientId,\n          parsedRef.host,\n          parsedRef.port\n        )\n        this.agentConnections.set(agentRef, agentConn)\n      }\n      let conn = this.containerConnections.get(uuid)\n      if (conn === undefined) {","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/net/packages/client/src/client.ts#L326-L362","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Wait for the container's endpoint ref update before connecting (subscribe to ref update events)","Validate the endpoint ref with parseEndpointRef before calling connect","Re-request the endpoint via container.endpoint / handleNewContainer to get a fresh ref","Check that the agent published the container endpoint correctly"],"exampleFix":"// before\nconst conn = client.conn(uuid) // may throw on bad ref\n// after\nconst ref = client.getEndpointRef?.(uuid)\nconst parsed = ref !== undefined ? parseEndpointRef(ref) : undefined\nif (parsed?.uuid !== undefined) {\n  const conn = client.conn(uuid)\n} else {\n  await waitForRefUpdate(uuid)\n}","handlingStrategy":"type-guard","validationCode":"const parsed = parseEndpointRef(endpoint)\nif (parsed.uuid === undefined) {\n  await waitForRefUpdate(uuid)\n}","typeGuard":"function isConnectableRef(endpoint: ContainerEndpointRef): boolean {\n  const p = parseEndpointRef(endpoint)\n  return p.uuid !== undefined && p.kind !== EndpointKind.noconnect\n}","tryCatchPattern":"try {\n  const conn = client.establishConnection(uuid, endpoint)\n} catch (e) {\n  if (e instanceof Error && e.message === 'Invalid endpoint reference') {\n    await waitForRefUpdate(uuid)\n  } else { throw e }\n}","preventionTips":["Wait for endpoint ref updates before connecting","Validate refs with parseEndpointRef first","Don't cache endpoint strings across reconnects","Check the agent published a real endpoint for the container"],"tags":["endpoint","connection","invalid-reference","parsing"],"backgroundTag":"invalid-endpoint-reference","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}