{"record":{"id":"ddff375af689939b","repo":"hcengineering/platform","slug":"router-is-not-bound-to-a-port","errorCode":null,"errorMessage":"Router is not bound to a port","messagePattern":"Router is not bound to a port","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"foundations/net/packages/backrpc/src/server.ts","lineNumber":125,"sourceCode":"  private handleClose (clientRecordId: ClientT, clientId: string, timeout: boolean): void {\n    void this.handlers.closeHandler?.(clientRecordId, timeout).catch((err) => {\n      console.error('Error in handleTimeout', err)\n    })\n    this.revClientMapping.delete(clientId)\n    this.clientMapping.delete(clientRecordId)\n  }\n\n  async getPort (): Promise<number> {\n    await this.bound\n    const reqEndpoint = this.router.lastEndpoint\n    if (reqEndpoint === null) {\n      throw new Error('Router is not bound to an endpoint')\n    }\n\n    const portMatch = reqEndpoint.match(/:(\\d+)$/)\n    const port = portMatch != null ? parseInt(portMatch[1]) : undefined\n    if (port === undefined) {\n      throw new Error('Router is not bound to a port')\n    }\n    return port\n  }\n\n  private sendPromise: Promise<void> | undefined\n\n  async doSend (msg: any[]): Promise<void> {\n    while (this.sendPromise !== undefined) {\n      await this.sendPromise\n    }\n    this.sendPromise = this.router.send(msg)\n    try {\n      await this.sendPromise\n    } catch (err: any) {\n      console.error('Failed to send message', err)\n    }\n    this.sendPromise = undefined\n  }","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/net/packages/backrpc/src/server.ts#L107-L143","documentation":"backrpc Server.getPort() parses the port from router.lastEndpoint via the regex /:(\\d+)$/. If the endpoint string doesn't end in `:<port>` (e.g. a Unix socket path, named pipe, or port-0 style endpoint), parseInt yields undefined and the server throws because it cannot determine a TCP port. The endpoint is bound, but not to a numeric port.","triggerScenarios":"Router bound to a non-TCP endpoint (Unix domain socket, named pipe) or an endpoint string without a trailing `:digits`, then calling getPort().","commonSituations":"Configuring the transport with a unix:/path-to-socket endpoint and then asking for a TCP port; binding to port 0 or a hostname-only endpoint; transport writing lastEndpoint in a format the regex doesn't match.","solutions":["Bind the router to a TCP endpoint with an explicit numeric port (e.g. host:port form ending in :8080).","If using a Unix socket/named pipe, read the socket path from the endpoint instead of calling getPort().","Check the lastEndpoint string format your transport produces and match the /:(\\d+)$/ expectation.","Specify a concrete port in configuration rather than an ephemeral or implicit one."],"exampleFix":"// before: bound to a unix socket, getPort() can't parse a port\nconst server = new Server({ endpoint: 'unix:/tmp/backrpc.sock' });\nconst port = await server.getPort(); // throws\n// after: bind to TCP with an explicit port\nconst server = new Server({ endpoint: '127.0.0.1:8080' });\nconst port = await server.getPort(); // 8080","handlingStrategy":"type-guard","validationCode":"function isTcpEndpoint(ep) { return typeof ep === 'string' && /:(\\d+)$/.test(ep); }\n// only call getPort() when the bound endpoint is TCP\nif (isTcpEndpoint(server.router.lastEndpoint)) { await server.getPort(); }","typeGuard":"function hasTcpEndpoint(server) {\n  const ep = server.router?.lastEndpoint;\n  return typeof ep === 'string' && /:(\\d+)$/.test(ep);\n}","tryCatchPattern":"try {\n  const port = await server.getPort();\n} catch (e) {\n  if (e.message === 'Router is not bound to a port') {\n    // endpoint exists but is not TCP (e.g. unix socket) — use the path instead\n    const socketPath = server.router.lastEndpoint;\n    console.log('Non-TCP endpoint:', socketPath);\n  } else throw e;\n}","preventionTips":["Use getPort() only for TCP endpoints; read socket paths directly for unix-socket transports.","Configure explicit host:port endpoints when a port is needed.","Check the endpoint format (trailing :port) before requesting a port."],"tags":["rpc","server","port","networking"],"backgroundTag":"server-not-bound","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}