{"record":{"id":"1d5c0fc54c896ec1","repo":"hcengineering/platform","slug":"agent-server-already-running-at-endpointurl","errorCode":null,"errorMessage":"Agent server already running at ${endpointUrl}","messagePattern":"Agent server already running at (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"foundations/net/packages/client/src/index.ts","lineNumber":57,"sourceCode":"    factory: Record<ContainerKind, ContainerFactory>,\n    statelessContainers?: StatelessContainersFactory\n  ) => Promise<void>\n}\n\nclass NetworkClientWithAgents extends NetworkClientImpl implements ClientWithAgents {\n  servers: [string, NetworkAgentServer][] = []\n\n  constructor (host: string, port: number, aliveTimeout?: number) {\n    super(host, port, new TickManagerImpl(timeouts.pingInterval * 2), aliveTimeout)\n  }\n\n  async serveAgent (\n    endpointUrl: string,\n    factory: Record<ContainerKind, ContainerFactory>,\n    statelessContainers?: StatelessContainersFactory\n  ): 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","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/net/packages/client/src/index.ts#L39-L75","documentation":"serveAgent starts a local agent RPC server bound to endpointUrl, but first checks the client's servers list and throws if a server is already registered on that exact URL. Prevents double-binding the same host:port endpoint within one NetworkClientImpl instance.","triggerScenarios":"Calling client.serveAgent(endpointUrl, ...) twice with the same 'host:port' string on the same client instance, e.g. re-invoking an init routine or registering the same endpoint in createHAAgent/registerBenchmark setup.","commonSituations":"Idempotency guard missing in bootstrap code that runs on reconnect; HA setup scripts calling serveAgent for the same endpoint on every retry; benchmark harness re-registering agents.","solutions":["Guard your init logic: only call serveAgent once per endpoint URL","Check whether the endpoint is already served (track your own set of served URLs) before calling","Use a different port/URL for the second agent instance","If restart is intended, create a fresh client or tear down the existing server first"],"exampleFix":"// before\nawait client.serveAgent('localhost:3738', factories) // called on every retry\n// after\nif (!servedEndpoints.has('localhost:3738')) {\n  await client.serveAgent('localhost:3738', factories)\n  servedEndpoints.add('localhost:3738')\n}","handlingStrategy":"validation","validationCode":"const servedUrls = new Set<string>()\nfunction canServe(url: string): boolean {\n  return !servedUrls.has(url)\n}","typeGuard":"function isUrlServed(url: string, servers: Array<[string, unknown]>): boolean {\n  return servers.some(([u]) => u === url)\n}","tryCatchPattern":"try {\n  await client.serveAgent(url, factories)\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Agent server already running')) {\n    // already initialized; skip\n  } else { throw e }\n}","preventionTips":["Make bootstrap/HA init idempotent with a served-URL set","Use unique ports per agent instance","Don't call serveAgent inside retry loops without guards","Track client instance lifetime to avoid double init"],"tags":["agent","server","duplicate-endpoint","initialization"],"backgroundTag":"agent-server-already-running","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}