Troubleshooting Access

Use this page when the app looks close to working, but users still cannot reach the protected product.

Symptom: sign-in works, but the workspace gate never clears

Check these in order:

1. confirm you are signed in with the same account that started checkout
2. confirm the user actually has product access
3. confirm Clerk + Convex auth is working with the convex template
4. confirm the webhook already granted access

If you skip any of those, you can chase the wrong problem for an hour.

The access-required page now shows the currently signed-in email for signed-in recovery states. Read that first. It is the fastest way to catch the common “wrong Clerk account” failure before you start debugging Stripe or Convex.

Symptom: /checkout/success keeps waiting

This usually means one of two things:

• the webhook never granted product access
• the app cannot read the right viewer state after payment

Go straight to Troubleshooting Stripe and Convex if payment already completed.

Symptom: a granted user sees Unauthorized during page load

That usually means the server-side access check succeeded, but a client-side Convex query fired before Clerk auth finished syncing in the browser.

Start with these checks:

1. confirm the user really has a granted product-access row
2. confirm the failing stack says Called by client, not the server-side layout guard
3. confirm the page is using the server-fetched initial access or mission data path before live Convex queries take over

If the access row exists and the error only appears during hydration, treat it as a Clerk/Convex client-auth timing issue, not a revoked purchase.

Symptom: the wrong-account state appears

That state is usually telling the truth.

Fix it by:

1. signing out
2. signing back in with the email shown in checkout or the access-granted QA account
3. reopening the validated success URL or retrying the access check from /access-required

Do not assume this is a Stripe bug first.

Symptom: a user with granted access still cannot reach /start

Check these in order:

1. run bun run clerk:test-user:prepare:entitled
2. confirm the user really has an active product-access row
3. confirm the Clerk convex template still matches the current app
4. confirm you are not signed into the wrong Clerk app or stale browser session

Local product-access sanity check

For the local granted-access QA user:

bun run clerk:test-user:prepare:entitled

If the granted-access test user still cannot reach /start, stop guessing and confirm the signed-in email shown on /access-required, then confirm the access row plus auth template path.

What success looks like

Access is healthy when:

• users without access reach /start and see inline recovery
• users with granted access reach /start
• a newly paid user leaves /checkout/success and reaches the protected workspace without manual intervention