{"record":{"id":"e583ecef66fe5586","repo":"hcengineering/platform","slug":"err-message-e583ec","errorCode":null,"errorMessage":"err.message","messagePattern":"err\\.message","errorType":"http","errorClass":null,"httpStatus":401,"severity":"error","filePath":"services/github/pod-github/src/server.ts","lineNumber":103,"sourceCode":"        workspaceName: decodedToken.workspace,\n        body: req.body\n      })\n\n      await ctx.with('map-installation', {}, (ctx) =>\n        worker.mapInstallation(ctx, decodedToken.workspace, payloadData.installationId, payloadData.accountId)\n      )\n      res.status(200)\n      res.json({})\n    } catch (err: any) {\n      Analytics.handleError(err)\n      const tok = decodeToken(payloadData.token, false)\n      ctx.error('failed to map-installation', {\n        workspace: tok.workspace,\n        installationid: payloadData.installationId,\n        email: tok?.account,\n        error: err.message\n      })\n      res.status(401)\n      res.json({ error: err.message })\n    }\n  })\n\n  // eslint-disable-next-line @typescript-eslint/no-misused-promises\n  app.post('/api/v1/auth', async (req, res) => {\n    try {\n      const payloadData: {\n        code: string\n        state: string\n        accountId: PersonId\n        token: string\n      } = req.body\n\n      const decodedData: {\n        accountId: PersonId\n        token: string\n        op: string","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/services/github/pod-github/src/server.ts#L85-L121","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the 'error' field of the 401 response — it carries the underlying message; fix that specific cause.","Obtain a fresh service token and retry; expired or cross-env tokens are the most common cause.","Verify the GitHub App installation is still active and the installationId belongs to the authenticated account.","Check github pod config (accounts URL, app credentials) if the error indicates an upstream lookup failure."],"exampleFix":"// before (stale token)\nawait githubApi.mapInstallation(oldToken, installationId)\n// after\nconst { token } = await login(currentUser)\nawait githubApi.mapInstallation(token, installationId)","handlingStrategy":"validation","validationCode":"// validate the token and installation payload before mapping\nif (typeof token !== 'string' || token.split('.').length !== 3) throw new Error('invalid service token')\nif (!Number.isInteger(payloadData.installationId)) throw new Error('installationId must be an integer')","typeGuard":null,"tryCatchPattern":"const res = await githubApi.mapInstallation(token, installationId)\nif (res.status === 401) {\n  const body = await res.json()\n  console.error(`map-installation rejected: ${body.error}`) // underlying cause in body.error\n  await refreshTokenAndRetry()\n}","preventionTips":["Refresh service tokens before integration setup flows","Confirm the GitHub App installation is active for the target org/user","Log the 'error' field from 401 responses — it names the exact upstream failure","Keep github pod account-service config aligned with the token issuer's environment"],"tags":["auth","http","github","integration"],"backgroundTag":"github-installation-auth-failed","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}