'User not found' right after signup: your database read raced the user.created webhook

TL;DR: Signup succeeds, then your app says the user does not exist. The webhook that creates your local row has not arrived yet. Confirm the cause 1. Check your logs: the failing request's timestamp vs the user.created delivery timestamp.

The error

user not found

The fix

1. Webhooks are asynchronous. user.created can arrive seconds after the user is already clicking around your app. Your first request raced the webhook and lost.
2. Check your logs: the failing request's timestamp vs the user.created delivery timestamp. If the request came first, this is the race.
3. Make the webhook handler an idempotent upsert keyed by the Clerk user id. Route user.created and user.updated through the same upsert so replays cannot create duplicates.
4. On the read path, handle a missing row: lazy-provision the user on first request, or fall back to fetching the user from Clerk's Backend API by id.
5. Key everything by the Clerk user id, never by email. Emails change; ids do not.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: 'User not found' right after signup.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current 'User behavior.

Verified 2026-09-26: Clerk delivers user lifecycle events (user.created, user.updated, user.deleted) via webhooks for syncing local user tables; community implementations use idempotent upserts keyed on the Clerk user id and key lookups by clerkId rather than email since emails can change.