hcengineering/platform · error

err.message

Error message

err.message

What it means

In the github pod's map-installation route, any error thrown while mapping a GitHub installation to a workspace/user (token decode, account lookup, GitHub API call) is caught, logged with ctx.error, and returned as HTTP 401 with { error: err.message }. The client sees the raw underlying error message under the 'error' key with a 401 status.

Source

Thrown at services/github/pod-github/src/server.ts:103

        workspaceName: decodedToken.workspace,
        body: req.body
      })

      await ctx.with('map-installation', {}, (ctx) =>
        worker.mapInstallation(ctx, decodedToken.workspace, payloadData.installationId, payloadData.accountId)
      )
      res.status(200)
      res.json({})
    } catch (err: any) {
      Analytics.handleError(err)
      const tok = decodeToken(payloadData.token, false)
      ctx.error('failed to map-installation', {
        workspace: tok.workspace,
        installationid: payloadData.installationId,
        email: tok?.account,
        error: err.message
      })
      res.status(401)
      res.json({ error: err.message })
    }
  })

  // eslint-disable-next-line @typescript-eslint/no-misused-promises
  app.post('/api/v1/auth', async (req, res) => {
    try {
      const payloadData: {
        code: string
        state: string
        accountId: PersonId
        token: string
      } = req.body

      const decodedData: {
        accountId: PersonId
        token: string
        op: string

View on GitHub (pinned to 63e28dc964)

Solutions

1. Read the 'error' field of the 401 response — it carries the underlying message; fix that specific cause.
2. Obtain a fresh service token and retry; expired or cross-env tokens are the most common cause.
3. Verify the GitHub App installation is still active and the installationId belongs to the authenticated account.
4. Check github pod config (accounts URL, app credentials) if the error indicates an upstream lookup failure.

Example fix

// before (stale token)
await githubApi.mapInstallation(oldToken, installationId)
// after
const { token } = await login(currentUser)
await githubApi.mapInstallation(token, installationId)

// validate the token and installation payload before mapping
if (typeof token !== 'string' || token.split('.').length !== 3) throw new Error('invalid service token')
if (!Number.isInteger(payloadData.installationId)) throw new Error('installationId must be an integer')

const res = await githubApi.mapInstallation(token, installationId)
if (res.status === 401) {
  const body = await res.json()
  console.error(`map-installation rejected: ${body.error}`) // underlying cause in body.error
  await refreshTokenAndRetry()
}

When it happens

Trigger: POST to the map-installation endpoint with an invalid/unverifiable service token (tok decode fails), a token lacking a valid workspace/account, or failures calling the accounts/GitHub APIs to associate payloadData.installationId.

Common situations: Expired service tokens after re-login, tokens from a different environment than the github pod expects, revoked GitHub App installations, or GitHub webhook payloads referencing installations the account cannot access.

Related errors

• Unauthorized
• Invalid workspace login info by token
• Github integration is not configured
• No status found for GH issue status ${pr.state} ${pr.stateRe
• Invalid workspace

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