hcengineering/platform · error

Global person not found

Error message

Global person not found

What it means

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.

Source

Thrown at services/mail/pod-mail-worker/src/workspaceClient.ts:91

  if (current !== undefined) {
    clients.delete(key)
    if (current instanceof Promise) {
      const resolvedClient = await current
      await resolvedClient.close()
    } else {
      await current.close()
    }
  }
}

async function createClient (workspaceUuid: WorkspaceUuid, socialId?: PersonId): Promise<TxOperations> {
  const token = generateToken(systemAccountUuid, workspaceUuid, { service: SERVICE_NAME })
  let accountClient = getAccountClient(config.accountsUrl, token)

  if (socialId !== undefined && socialId !== core.account.System) {
    const personUuid = await accountClient.findPersonBySocialId(socialId, true)
    if (personUuid === undefined) {
      throw new Error('Global person not found')
    }
    const token = generateToken(personUuid, workspaceUuid, { service: SERVICE_NAME })
    accountClient = getAccountClient(config.accountsUrl, token)
  }

  const wsInfo = await accountClient.getLoginInfoByToken()
  if (wsInfo == null || !('endpoint' in wsInfo)) {
    throw new Error('Invalid login info')
  }
  const transactorUrl = wsInfo.endpoint.replace('ws://', 'http://').replace('wss://', 'https://')
  const client = await createRestTxOperations(transactorUrl, wsInfo.workspace, wsInfo.token, true)
  return client
}

View on GitHub (pinned to 63e28dc964)

Solutions

  1. Verify the socialId exists by querying the account service directly (findPersonBySocialId) and confirm the expected format
  2. Ensure the sender's social account is registered/verified (sign-up or social integration) before emails from them are processed
  3. Correct the socialId extraction logic if it derives the id from the wrong header/platform
  4. If the sender may legitimately be unknown, catch this and route the message to a fallback/system identity instead of a specific person

Example fix

// before
const client = await createClient(ctx, socialId, workspaceUuid)
// after
let client
try {
  client = await createClient(ctx, socialId, workspaceUuid)
} catch (e) {
  if (e.message.includes('Global person not found')) {
    client = await createClient(ctx, core.account.System, workspaceUuid)
  } else throw e
}
Defensive patterns

Strategy: try-catch

Validate before calling

const personUuid = await getAccountClient(config.accountsUrl, systemToken).findPersonBySocialId(socialId, true)
if (personUuid === undefined) throw new Error(`Skipping: unknown social id ${socialId}`)

Type guard

async function personExists(accountUrl: string, token: string, socialId: string): Promise<boolean> {
  return (await getAccountClient(accountUrl, token).findPersonBySocialId(socialId, true)) !== undefined
}

Try / catch

try {
  client = await createClient(ctx, socialId, workspaceUuid)
} catch (e) {
  if (e.message === 'Global person not found') {
    client = await createClient(ctx, core.account.System, workspaceUuid)
  } else throw e
}

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/8c6b55e092f7fec8. Report an issue: GitHub.