{"record":{"id":"94d09d82ea49a01b","repo":"hcengineering/platform","slug":"client-clientid-not-found","errorCode":null,"errorMessage":"Client ${clientId} not found","messagePattern":"Client (.+?) not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"foundations/net/packages/backrpc/src/server.ts","lineNumber":314,"sourceCode":"              const { message, stack } = parseJSON(payload.toString())\n              req?.reject(new Error(message + '\\n' + stack))\n            } catch (err: any) {\n              console.error(err)\n            }\n            this.backRequests.delete(reqID)\n            break\n          }\n        }\n      } catch (err: any) {\n        console.error(err)\n      }\n    }\n  }\n\n  async request (clientId: ClientT, method: string, params: any): Promise<any> {\n    const clientIdentity = this.clientMapping.get(clientId)\n    if (clientIdentity === undefined) {\n      throw new Error(`Client ${clientId} not found`)\n    }\n    return await new Promise<any>((resolve, reject) => {\n      const reqId = clientId + '-' + this.requestCounter++\n      this.backRequests.set(reqId, { resolve, reject })\n\n      void this.doSend([clientIdentity, backrpcOperations.request, reqId, stringifyJSON([method, params])]).catch(\n        (err) => {\n          reject(err)\n        }\n      )\n    })\n  }\n\n  async send (clientId: ClientT, body: any): Promise<any> {\n    const clientIdentity = this.clientMapping.get(clientId)\n    if (clientIdentity === undefined) {\n      throw new Error(`Client ${clientId as string} not found`)\n    }","sourceCodeStart":296,"sourceCodeEnd":332,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/net/packages/backrpc/src/server.ts#L296-L332","documentation":"BackRPC server's request() sends a back-channel RPC request to a connected client, but the given clientId has no mapping to an underlying transport identity. The server throws because it cannot route the request to an unknown client. This indicates the client was never connected, or has since disconnected and been removed from clientMapping.","triggerScenarios":"Calling server.request(clientId, method, params) with a clientId that was never registered via hello, or whose connection was closed and pruned from clientMapping before the call.","commonSituations":"Race after client disconnect: caller holds a stale clientId from an earlier session and sends a request; load-balanced setup where the request lands on a server instance the client never connected to; client restart produced a new UUID.","solutions":["Verify the clientId exists before calling request by tracking registrations from the hello/handshake path","Reconnect or re-handshake the client to obtain a fresh clientId and retry","Handle the thrown error by removing the stale client reference from caller state","Check for client disconnects between obtaining the clientId and issuing the request"],"exampleFix":"// before\nawait server.request(clientId, 'op', params) // throws if client gone\n// after\nif (server.hasClient(clientId)) { // track registration yourself if no such helper\n  await server.request(clientId, 'op', params)\n} else {\n  await reconnectAndRetry(clientId)\n}","handlingStrategy":"try-catch","validationCode":"// maintain your own registry of live clientIds\nfunction isClientLive(clientId: string): boolean {\n  return liveClients.has(clientId)\n}","typeGuard":"function hasClient(mapping: Map<ClientT, unknown>, clientId: ClientT): clientId is ClientT {\n  return mapping.has(clientId)\n}","tryCatchPattern":"try {\n  await server.request(clientId, method, params)\n} catch (e) {\n  if (e instanceof Error && e.message === `Client ${clientId} not found`) {\n    dropStaleClient(clientId)\n  } else { throw e }\n}","preventionTips":["Register clientIds only from the hello/handshake path","Remove clientIds on disconnect events","Never cache clientIds across server restarts","Log client lifetimes to spot races"],"tags":["rpc","backrpc","unknown-client","stale-reference"],"backgroundTag":"rpc-client-not-found","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}