hcengineering/platform · warning

No gmail clients found for social id

Error message

No gmail clients found for social id

What it means

This is an HTTP 404 response body returned by the GET integration-state endpoint in pod-gmail. It means no Gmail client (stored integration state) exists for the given socialId in the workspace, so getState returned undefined. It is a lookup miss, not an internal failure.

Source

Thrown at services/gmail/pod-gmail/src/main.ts:193

      type: 'get',
      handler: async (req, res) => {
        try {
          const token = extractToken(req.headers)

          if (token === undefined) {
            res.status(401).send()
            return
          }

          const { workspace } = decodeToken(token)
          const socialId = req.query.socialId as PersonId | undefined
          if (socialId == null || socialId === '') {
            res.status(400).send({ error: 'Missing socialId param' })
            return
          }
          const state = await gmailController.getState(workspace, socialId)
          if (state === undefined) {
            res.status(404).send({ error: 'No gmail clients found for social id' })
            return
          }
          res.send(state)
        } catch (err: any) {
          ctx.error('Failed to get integration state', { message: err.message })
          res.status(500).send({ error: err.message })
        }
      }
    },
    {
      endpoint: '/start-sync',
      type: 'post',
      handler: async (req, res) => {
        try {
          const token = extractToken(req.headers)

          if (token === undefined) {
            res.status(401).send()

View on GitHub (pinned to 63e28dc964)

Solutions

1. Verify the socialId exists in the same workspace's database and matches the id stored when the Gmail client was connected
2. Re-run the Gmail OAuth connect flow for this socialId so state is persisted
3. Check for workspace mismatch — pass the socialId scoped to the workspace encoded in the auth context
4. Log the socialId received vs. known ids to catch encoding/whitespace issues

Example fix

// before
const state = await gmailController.getState(workspace, socialId)
res.send(state)
// after
const state = await gmailController.getState(workspace, socialId)
if (state === undefined) {
  res.status(404).send({ error: 'No gmail clients found for social id' })
  return
}
res.send(state)

if (!socialId) throw new Error('socialId required before querying gmail integration state')
const known = await hasGmailClient(workspace, socialId)
if (!known) console.warn(`no gmail client for socialId=${socialId}`)

function isStateDefined<T>(state: T | undefined): state is T {
  return state !== undefined
}

try {
  const res = await fetch(`${base}/integration-state?socialId=${id}`)
  if (res.status === 404) {
    console.warn('Gmail not connected for this social id — run connect flow first')
    return null
  }
  return await res.json()
} catch (e) {
  console.error('integration-state lookup failed', e)
  return null
}

When it happens

Trigger: Calling GET /integration-state (or equivalent) with a socialId that has never completed Gmail OAuth enrollment, a socialId belonging to another workspace, or a stale/deleted socialId.

Common situations: Frontend passes a person/social id from a different system than the one pod-gmail is keyed on; the integration was disconnected and state was deleted; trailing whitespace or URL-encoding differences in the socialId param.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• platform.status.ResourceNotFound
• err.message
• Not found
• Not found
• Subscription not found

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