hcengineering/platform · error

Agent endpoint not initialized after server start

Error message

Agent endpoint not initialized after server start

What it means

serveAgent starts a server for an agent and then, when stateless container factories are provided, reads agent.endpoint to hand the live URL to those factories. If the endpoint is still undefined after the server has been started, the wiring is broken, so the library throws rather than calling the factories with an unusable value. It is an internal invariant check that server startup actually produced a reachable address.

Source

Thrown at foundations/net/packages/client/src/index.ts:73

  ): Promise<void> {
    if (this.servers.find((s) => s[0] === endpointUrl) != null) {
      throw new Error(`Agent server already running at ${endpointUrl}`)
    }
    const agent = new AgentImpl(uuidv4() as AgentUuid, factory)

    const [host, portStr] = endpointUrl.split(':')
    const port = portStr != null ? parseInt(portStr, 10) : 3738

    const server = new NetworkAgentServer(this.tickMgr, host, '*', port)
    this.servers.push([endpointUrl, server])
    await server.start(agent)

    // Add stateless containers if provided
    if (statelessContainers != null) {
      // Get the agent endpoint after server starts - it should be initialized
      const agentEndpoint = agent.endpoint
      if (agentEndpoint === undefined) {
        throw new Error('Agent endpoint not initialized after server start')
      }

      const configs = await statelessContainers(agentEndpoint)
      for (const config of configs) {
        agent.addStatelessContainer(config.uuid, config.kind, config.endpoint, config.container)
      }
    }

    await this.register(agent)
  }

  async close (): Promise<void> {
    this.tickMgr.stop()
    for (const [, server] of this.servers) {
      await server.close()
    }
    await super.close()
  }

View on GitHub (pinned to 63e28dc964)

Solutions

1. Inspect why the server did not produce an endpoint: enable transport logs, check for bind/port errors during server start inside serveAgent.
2. Verify the agent/server object passed to serveAgent is the library's own implementation (which sets endpoint on start), not a partial or custom stub.
3. Free the configured port or pick another one if binding failed, then retry serveAgent.
4. If on a custom network stack, set agent.endpoint after start before passing statelessContainers, or upgrade to a version where endpoint is awaited/assigned after server start.

Example fix

// before
const agent = new MyAgent(customServerWithoutEndpoint)
await serveAgent(agent, { statelessContainers })
// after
const agent = createHAAgent() // library-managed server that assigns endpoint on start
await serveAgent(agent, { statelessContainers })
// or assert endpoint before use
if (agent.endpoint === undefined) throw new Error('server did not expose endpoint')

await serveAgent(agent, { statelessContainers }) // wrap:
if (typeof agent.endpoint !== 'string' || agent.endpoint.length === 0) {
  throw new Error('server did not initialize agent.endpoint; cannot attach stateless containers')
}

function hasEndpoint(a: { endpoint?: string }): a is { endpoint: string } {
  return typeof a.endpoint === 'string' && a.endpoint.length > 0
}

try {
  await serveAgent(agent, { statelessContainers })
} catch (e) {
  if ((e as Error).message.includes('endpoint not initialized')) {
    console.error('server failed to expose an endpoint; check bind/port errors', e)
    // fall back or abort startup
  } else throw e
}

When it happens

Trigger: Calling serveAgent (directly or via createHAAgent/registerBenchmark) with a statelessContainers callback while the underlying server/agent never populated agent.endpoint — e.g. the server failed to bind or was constructed without a listener/address, so `agent.endpoint` remains undefined at the point of the check.

Common situations: Server port binding silently failed (port in use, permission denied) yet startup resolved; passing a custom server/agent object whose endpoint property is never set; calling serveAgent before the transport finished initializing; version drift where the server no longer sets `endpoint` synchronously after start.

Related errors

• Hierarchy is not defined
• Model is not defined
• Router is not bound to an endpoint
• Router is not bound to a port
• Invalid endpoint reference

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