{"record":{"id":"0533b74865969231","repo":"hcengineering/platform","slug":"integrationnotfound","errorCode":"IntegrationNotFound","errorMessage":"IntegrationNotFound","messagePattern":"IntegrationNotFound","errorType":"exception","errorClass":"PlatformError","httpStatus":null,"severity":"error","filePath":"server/account/src/serviceOperations.ts","lineNumber":692,"sourceCode":"  if (social?.personUuid === readOnlyGuestAccountUuid) {\n    throw new PlatformError(new Status(Severity.ERROR, platform.status.Forbidden, {}))\n  }\n\n  await db.integration.insertOne({ socialId, kind, workspaceUuid, data })\n}\n\nexport async function updateIntegration (\n  ctx: MeasureContext,\n  db: AccountDB,\n  branding: Branding | null,\n  token: string,\n  params: Integration\n): Promise<void> {\n  const { extra, account } = decodeTokenVerbose(ctx, token)\n  // it checks params and throws BadRequest if params are invalid\n  const existing = await findExistingIntegration(account, db, params, extra)\n  if (existing == null) {\n    throw new PlatformError(new Status(Severity.ERROR, platform.status.IntegrationNotFound, {}))\n  }\n\n  const { socialId, kind, workspaceUuid, data } = params\n  await db.integration.update({ socialId, kind, workspaceUuid }, { data })\n}\n\nexport async function deleteIntegration (\n  ctx: MeasureContext,\n  db: AccountDB,\n  branding: Branding | null,\n  token: string,\n  params: IntegrationKey\n): Promise<void> {\n  const { extra, account } = decodeTokenVerbose(ctx, token)\n  // it checks params and throws BadRequest if params are invalid\n  const existing = await findExistingIntegration(account, db, params, extra)\n  if (existing == null) {\n    throw new PlatformError(new Status(Severity.ERROR, platform.status.IntegrationNotFound, {}))","sourceCodeStart":674,"sourceCodeEnd":710,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/server/account/src/serviceOperations.ts#L674-L710","documentation":"IntegrationNotFound is thrown by updateIntegration when findExistingIntegration returns null — no integration exists for the given (socialId, kind, workspaceUuid) key (or the caller is not allowed to see it). The service refuses to update a non-existent record rather than silently upserting. Before reaching this check, findExistingIntegration also validates params and ownership, so a null can follow a failed ownership path only if Forbidden/SocialIdNotFound were not already raised.","triggerScenarios":"Calling updateIntegration with a key tuple that was never created, was already deleted via deleteIntegration, or with a workspaceUuid that differs from the one used at creation time.","commonSituations":"Environment/config drift where the client points at a different DB or workspace; re-running a setup script against a fresh database; changing workspaceUuid casing/format after migration; racing with a concurrent deleteIntegration.","solutions":["Call getIntegration first and create the integration via createIntegration when it is missing (upsert pattern).","Verify the exact socialId/kind/workspaceUuid triple matches the one used at creation.","Check you are connected to the intended account-service database/environment.","Confirm the integration was not deleted by a concurrent process or another team member."],"exampleFix":"// before\nawait client.updateIntegration(ctx, token, { socialId, kind: 'gmail', workspaceUuid, data })\n// after\nconst existing = await client.getIntegration(ctx, token, { socialId, kind: 'gmail', workspaceUuid })\nif (existing == null) {\n  await client.createIntegration(ctx, token, { socialId, kind: 'gmail', workspaceUuid, data })\n} else {\n  await client.updateIntegration(ctx, token, { socialId, kind: 'gmail', workspaceUuid, data })\n}","handlingStrategy":"validation","validationCode":"const existing = await client.getIntegration(ctx, token, { socialId, kind, workspaceUuid })\nif (existing == null) {\n  await client.createIntegration(ctx, token, { socialId, kind, workspaceUuid, data })\n}","typeGuard":"function canUpdateKey(p: Integration): p is Integration & { workspaceUuid: string } {\n  return p.kind != null && p.kind !== '' && p.socialId != null && p.socialId !== '' && p.workspaceUuid !== undefined\n}","tryCatchPattern":"try {\n  await client.updateIntegration(ctx, token, params)\n} catch (err) {\n  if (err instanceof PlatformError && err.status.code === platform.status.IntegrationNotFound) {\n    await client.createIntegration(ctx, token, params) // upsert fallback\n    return\n  }\n  throw err\n}","preventionTips":["Always fetch the integration first and upsert","Freeze the socialId/kind/workspaceUuid triple per integration in app state","Verify environment/DB consistency between creation and update code paths","Log the full key on failure to spot mismatched workspaceUuid"],"tags":["not-found","integration","upsert"],"backgroundTag":"entity-not-found","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}