History

Every saved version of bugs/clerk-provisioning-race.md, newest first. Each row shows what changed compared to the version before it.

• v1currentCreatedby agent · 18d ago
  Initial content

  # Clerk user provisioning race on first sign-in
  
  ## Symptom
  
  On first Clerk sign-in, the Vercel-deployed web showed a "Something went wrong" error page. Refreshing the browser made everything work — the user landed on `/onboarding` cleanly.
  
  API logs at the time:
  
  ```
  [GET] /v1/wikis     → 500
  [GET] /v1/users/me  → 500
  [GET] /v1/users/me  → 200  (after refresh)
  [GET] /v1/wikis     → 200
  ```
  
  With error detail:
  
  ```
  PostgresError: duplicate key value violates unique constraint "users_clerk_id_key"
  Key (clerk_id)=(user_3Dgtsu5H8XlFWfxrlTns3Bp5qeg) already exists.
    at provisionUserFromClerk (file:///app/dist/lib/clerk.js:48:23)
  ```
  
  ## Root cause
  
  On first sign-in, Next's SSR fires multiple parallel API fetches against an unprovisioned user — `/v1/users/me` from the dashboard layout, `/v1/wikis` from the dashboard page, plus a handful of others from sidebar/wiki-shell. Each hits the auth middleware (`packages/api/src/middleware/auth.ts:80`), finds no row for that `clerkId`, and races to `INSERT` one. The first wins; the rest crash on the unique constraint and return 500.
  
  The Refresh "fix" worked because by then the row existed and `provisionUserFromClerk` was a no-op for the second-and-later concurrent callers — but only if you survived the first attempt.
  
  ## Fix
  
  Make provisioning idempotent. `INSERT ... ON CONFLICT DO NOTHING RETURNING *` plus a fallback `SELECT` so every concurrent caller converges on the same row:
  
  ```ts
  // packages/api/src/lib/clerk.ts
  const [created] = await db
    .insert(users)
    .values({ clerkId, username, displayName, email, avatarUrl, avatarUrlManual: false })
    .onConflictDoNothing({ target: users.clerkId })
    .returning();
  if (created) return created;
  
  // Another concurrent provisioner won — fetch their row.
  const existing = await db.query.users.findFirst({ where: eq(users.clerkId, clerkId) });
  if (!existing) throw new Error('Failed to provision user');
  return existing;
  ```
  
  Belt-and-suspenders in the web layer too — `getCurrentUserRow` (`packages/web/src/lib/server-api.ts:47`) retries 3× with backoff (covers cold-start latency), and the dashboard layout redirects to `/onboarding` if the user fetch still comes back null, rather than rendering a broken dashboard with no user state.
  
  Commit: `2cb08c3` (`fix: make Clerk user provisioning concurrent-safe`).
  
  ## What made it hard to spot
  
  - **The Refresh masked it** — every developer's first instinct ("must be a flake") was the wrong instinct.
  - **The crash trace was on the LOSERS of the race, not the winner**, so reading the stack pointed at `provisionUserFromClerk` insert path — but inserting was fine. The real problem was upstream: multiple callers racing into the same code path with no idempotency guard.
  - **Vercel's "Something went wrong" page** swallowed the underlying response, requiring a trip into Railway logs to see the unique-constraint violation. Easy to assume it was a Clerk SDK error rather than a DB write race.
  
  Lesson: any code path that reads-then-writes on first observation needs an idempotency guard, especially when SSR makes parallel calls inevitable. Apply the same pattern to other "lazy upsert" paths if they exist.