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:

// 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.