{"record":{"id":"8c6b55e092f7fec8","repo":"hcengineering/platform","slug":"global-person-not-found","errorCode":null,"errorMessage":"Global person not found","messagePattern":"Global person not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"services/mail/pod-mail-worker/src/workspaceClient.ts","lineNumber":91,"sourceCode":"  if (current !== undefined) {\n    clients.delete(key)\n    if (current instanceof Promise) {\n      const resolvedClient = await current\n      await resolvedClient.close()\n    } else {\n      await current.close()\n    }\n  }\n}\n\nasync function createClient (workspaceUuid: WorkspaceUuid, socialId?: PersonId): Promise<TxOperations> {\n  const token = generateToken(systemAccountUuid, workspaceUuid, { service: SERVICE_NAME })\n  let accountClient = getAccountClient(config.accountsUrl, token)\n\n  if (socialId !== undefined && socialId !== core.account.System) {\n    const personUuid = await accountClient.findPersonBySocialId(socialId, true)\n    if (personUuid === undefined) {\n      throw new Error('Global person not found')\n    }\n    const token = generateToken(personUuid, workspaceUuid, { service: SERVICE_NAME })\n    accountClient = getAccountClient(config.accountsUrl, token)\n  }\n\n  const wsInfo = await accountClient.getLoginInfoByToken()\n  if (wsInfo == null || !('endpoint' in wsInfo)) {\n    throw new Error('Invalid login info')\n  }\n  const transactorUrl = wsInfo.endpoint.replace('ws://', 'http://').replace('wss://', 'https://')\n  const client = await createRestTxOperations(transactorUrl, wsInfo.workspace, wsInfo.token, true)\n  return client\n}\n","sourceCodeStart":73,"sourceCodeEnd":105,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/services/mail/pod-mail-worker/src/workspaceClient.ts#L73-L105","documentation":"createClient in pod-mail-worker resolves a workspace account client. When a socialId is supplied (and is not the System account), it asks the account service for the global person UUID via findPersonBySocialId; if the account service returns undefined, the social identity has no matching global person record, and the client throws 'Global person not found'. This is a data-lookup failure, meaning the email author's social identity is unknown to the platform.","triggerScenarios":"createClient called with a socialId that does not exist in the account service (findPersonBySocialId returns undefined), e.g. an email from an address never registered/verified in any workspace, or a socialId string in the wrong format (wrong platform prefix).","commonSituations":"Emails from external senders not yet signed up; socialId extracted from a From address with a mismatching social platform; account DB replicated incompletely across regions; System-check pass but stale social entry after account deletion.","solutions":["Verify the socialId exists by querying the account service directly (findPersonBySocialId) and confirm the expected format","Ensure the sender's social account is registered/verified (sign-up or social integration) before emails from them are processed","Correct the socialId extraction logic if it derives the id from the wrong header/platform","If the sender may legitimately be unknown, catch this and route the message to a fallback/system identity instead of a specific person"],"exampleFix":"// before\nconst client = await createClient(ctx, socialId, workspaceUuid)\n// after\nlet client\ntry {\n  client = await createClient(ctx, socialId, workspaceUuid)\n} catch (e) {\n  if (e.message.includes('Global person not found')) {\n    client = await createClient(ctx, core.account.System, workspaceUuid)\n  } else throw e\n}","handlingStrategy":"try-catch","validationCode":"const personUuid = await getAccountClient(config.accountsUrl, systemToken).findPersonBySocialId(socialId, true)\nif (personUuid === undefined) throw new Error(`Skipping: unknown social id ${socialId}`)","typeGuard":"async function personExists(accountUrl: string, token: string, socialId: string): Promise<boolean> {\n  return (await getAccountClient(accountUrl, token).findPersonBySocialId(socialId, true)) !== undefined\n}","tryCatchPattern":"try {\n  client = await createClient(ctx, socialId, workspaceUuid)\n} catch (e) {\n  if (e.message === 'Global person not found') {\n    client = await createClient(ctx, core.account.System, workspaceUuid)\n  } else throw e\n}","preventionTips":["Validate socialId format (platform prefix) before lookup","Handle senders without accounts by routing to a system/default identity","Watch for account deletions that orphan queued emails","Add integration coverage for unknown-sender emails"],"tags":["identity","account","lookup","email"],"backgroundTag":"person-not-found","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}