hcengineering/platform · error

Reference not found

Error message

Reference not found

What it means

The container wrapper's endpoint getter looks up the container's UUID in the client's references map to expose its endpoint reference. If the UUID is absent, the reference was never established or has been released, so it throws instead of returning undefined. Accessing endpoint on a closed/released container is invalid.

Source

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

import { ContainerConnectionImpl, NetworkDirectConnectionImpl, RoutedNetworkAgentConnectionImpl } from './agent'
import { opNames } from './types'

interface ClientAgentRecord {
  agent: NetworkAgent
  register: Promise<void>
  resolve: () => void
}

class ContainerReferenceImpl implements ContainerReference {
  constructor (
    readonly uuid: ContainerUuid,
    private readonly client: NetworkClientImpl
  ) {}

  get endpoint (): ContainerEndpointRef {
    const ref = this.client.references.get(this.uuid)
    if (ref === undefined) {
      throw new Error('Reference not found')
    }
    return ref.endpoint
  }

  async close (): Promise<void> {
    await this.client.release(this.uuid)
    this.client.references.delete(this.uuid)
  }

  async request (operation: string, data?: any): Promise<any> {
    return await this.client.request(this.uuid, operation, data)
  }

  cast<T extends object>(interfaceName?: string): T {
    return createProxy<T>(this, interfaceName)
  }

  async connect (): Promise<ContainerConnection> {

View on GitHub (pinned to 63e28dc964)

Solutions

1. Do not access endpoint after close/release; capture the endpoint value earlier if needed
2. Re-create the container or re-acquire the reference before reading endpoint
3. Track container lifecycle and skip endpoint access for released UUIDs
4. Check references.has(uuid) before accessing endpoint

Example fix

// before
const ep = container.endpoint // throws if released
await container.close()
// after
const ep = container.endpoint
await container.close()
// never touch container.endpoint again; use saved ep if needed

if (client.references?.get(container.uuid) === undefined) {
  throw new Error('Container already released')
}

function hasReference(client: NetworkClientImpl, uuid: ContainerUuid): boolean {
  return client.references.get(uuid) !== undefined
}

let ep: ContainerEndpointRef
try {
  ep = container.endpoint
} catch (e) {
  if (e instanceof Error && e.message === 'Reference not found') {
    ep = await reacquireEndpoint(container.uuid)
  } else { throw e }
}

When it happens

Trigger: Reading container.endpoint after client.release(uuid) or container.close(); accessing endpoint on a container whose reference registration failed; passing a constructed Container object whose uuid was never registered with the client.

Common situations: Double-close patterns where code touches endpoint in a finally block after release; containers invalidated by endpoint-change events that dropped references; holding Container objects across reconnects.

Related errors

• Hierarchy is not defined
• Model is not defined
• Container not found
• Card not found, _id: ${ref}
• ConnectionClosed

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