Local Dev Issues

When local development feels flaky, start with the environment before you assume the code is wrong.

Symptom: the page looks stale

This usually means the local app process or the hosted Convex dev deployment state are out of sync.

Try this first:

stop the running local services
start them again with bun run dev
reload the flow and retry the exact steps

If the issue started after switching Convex deployments, rerun bun run dev:convex before you retry the browser flow.

Symptom: env changes do not seem to apply

Check these in order:

confirm you changed .env.local
restart the app after the env change
if Stripe rewrote the webhook secret, restart the app again
confirm Convex and the app are using the same updated values
confirm NEXT_PUBLIC_CONVEX_URL and CONVEX_DEPLOYMENT still point at the same hosted Convex dev deployment

Symptom: local checkout behaves inconsistently

Use http://localhost:3000 consistently.

Do not mix:

localhost
127.0.0.1

That drift can break return URLs and local verification assumptions.

Symptom: the browser flow and the terminal disagree

Run the built-in checks instead of guessing:


bun run build
bun run stripe:dev:doctor

bun run stripe:dev:doctor now compares the app Stripe account in .env.local with the pinned Stripe CLI project ship-by-sunday. If it reports a missing or mismatched CLI project, repair that exact profile with stripe login --project-name ship-by-sunday before assuming webhook code is broken.

Symptom: `/access-required` looks wrong even though you expected access