{"record":{"id":"c774750ca1be145c","repo":"hcengineering/platform","slug":"agent-endpoint-not-initialized-after-server-start","errorCode":null,"errorMessage":"Agent endpoint not initialized after server start","messagePattern":"Agent endpoint not initialized after server start","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"foundations/net/packages/client/src/index.ts","lineNumber":73,"sourceCode":"  ): Promise<void> {\n    if (this.servers.find((s) => s[0] === endpointUrl) != null) {\n      throw new Error(`Agent server already running at ${endpointUrl}`)\n    }\n    const agent = new AgentImpl(uuidv4() as AgentUuid, factory)\n\n    const [host, portStr] = endpointUrl.split(':')\n    const port = portStr != null ? parseInt(portStr, 10) : 3738\n\n    const server = new NetworkAgentServer(this.tickMgr, host, '*', port)\n    this.servers.push([endpointUrl, server])\n    await server.start(agent)\n\n    // Add stateless containers if provided\n    if (statelessContainers != null) {\n      // Get the agent endpoint after server starts - it should be initialized\n      const agentEndpoint = agent.endpoint\n      if (agentEndpoint === undefined) {\n        throw new Error('Agent endpoint not initialized after server start')\n      }\n\n      const configs = await statelessContainers(agentEndpoint)\n      for (const config of configs) {\n        agent.addStatelessContainer(config.uuid, config.kind, config.endpoint, config.container)\n      }\n    }\n\n    await this.register(agent)\n  }\n\n  async close (): Promise<void> {\n    this.tickMgr.stop()\n    for (const [, server] of this.servers) {\n      await server.close()\n    }\n    await super.close()\n  }","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/net/packages/client/src/index.ts#L55-L91","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect why the server did not produce an endpoint: enable transport logs, check for bind/port errors during server start inside serveAgent.","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.","Free the configured port or pick another one if binding failed, then retry serveAgent.","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."],"exampleFix":"// before\nconst agent = new MyAgent(customServerWithoutEndpoint)\nawait serveAgent(agent, { statelessContainers })\n// after\nconst agent = createHAAgent() // library-managed server that assigns endpoint on start\nawait serveAgent(agent, { statelessContainers })\n// or assert endpoint before use\nif (agent.endpoint === undefined) throw new Error('server did not expose endpoint')","handlingStrategy":"validation","validationCode":"await serveAgent(agent, { statelessContainers }) // wrap:\nif (typeof agent.endpoint !== 'string' || agent.endpoint.length === 0) {\n  throw new Error('server did not initialize agent.endpoint; cannot attach stateless containers')\n}","typeGuard":"function hasEndpoint(a: { endpoint?: string }): a is { endpoint: string } {\n  return typeof a.endpoint === 'string' && a.endpoint.length > 0\n}","tryCatchPattern":"try {\n  await serveAgent(agent, { statelessContainers })\n} catch (e) {\n  if ((e as Error).message.includes('endpoint not initialized')) {\n    console.error('server failed to expose an endpoint; check bind/port errors', e)\n    // fall back or abort startup\n  } else throw e\n}","preventionTips":["Use the library's own createHAAgent/server constructors rather than custom stubs so endpoint is set on start.","Check server bind logs for port conflicts before attaching stateless containers.","Add a startup smoke test that asserts agent.endpoint is defined after serveAgent.","Pin package versions so server internals that assign endpoint do not drift."],"tags":["server-startup","endpoint","initialization","networking"],"backgroundTag":"endpoint-not-initialized","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}