Troubleshooting

Why does setup use a “dev” Convex URL (*.convex.cloud)?

Convex has two deployments per project:

• Development — npx convex dev --once, local npm run dev
• Production — Vercel, npm run build / convex deploy, buyer traffic

convex dev --once always pushes to Development. That is expected. Your live portfolio on Vercel still uses Production URLs and env vars (--prod).

Setup fails on Development env with 401 MissingAccessToken

Cause:

• CONVEX_DEPLOY_KEY only works for Production (--prod).
• If that key is in your shell or .env.local, the CLI skips your login token and Development commands fail.

Fix:

unset CONVEX_DEPLOY_KEY
export CONVEX_DEPLOYMENT=dev:your-project-slug
npx convex env set SITE_URL http://localhost:3000
npx convex env set BETTER_AUTH_SECRET "your-secret"

Do not put CONVEX_DEPLOY_KEY in .env.local (Vercel only).

Setup fails with No CONVEX_DEPLOYMENT set

Cause:

• convex env set (Development) only works after the project is linked.
• Linking happens in npx convex dev --once, which writes CONVEX_DEPLOYMENT to .env.local.

Fix:

1. Run npx convex login
2. Run npx convex dev --once and finish the prompts (create or choose a project)
3. Run npm run setup again, or set Development env vars manually:

npx convex env set SITE_URL http://localhost:3000
npx convex env set BETTER_AUTH_SECRET "your-secret-here"

Setup fails at npx convex dev --once with SITE_URL is not set in Convex

Cause:

• Development deployment is missing SITE_URL / BETTER_AUTH_SECRET (auth needs them at runtime).

Fix:

1. Finish npx convex dev --once if linking succeeded
2. Set Development env vars (dashboard or CLI commands above)
3. Re-run npm run setup or continue the wizard

Production (--prod) vars are still set later in setup for your live Vercel URL.

Build fails with SITE_URL is not set in Convex

Cause:

• Convex Production env var SITE_URL is missing (or set on wrong deployment).

Fix:

1. Convex dashboard → Project → Settings → Environment Variables (Production)
2. Set:
   • SITE_URL=https://your-vercel-url
   • BETTER_AUTH_SECRET=<same as Vercel>
3. Run setup again or redeploy on Vercel

Invalid origin on login

Cause:

• URL mismatch between app and Convex auth env.

Fix:

• Vercel NEXT_PUBLIC_SITE_URL must equal Convex SITE_URL (Production)
• Both should be your live app URL

Redirect loop / 508 auth errors

Cause:

• NEXT_PUBLIC_CONVEX_SITE_URL set to app URL instead of Convex site URL.

Fix:

• Use Convex URL ending in .convex.site
• Do not use https://your-app.vercel.app for this variable

Setup gets stuck after login commands

If CLI interaction is interrupted:

1. Press Ctrl+C
2. Run npm run setup again
3. Answer prompts again

The wizard is safe to re-run.

Vercel assigned a different domain than expected

Example:

• expected https://my-site.vercel.app
• got https://my-site-abc123.vercel.app

Fix:

Update both:

• Vercel NEXT_PUBLIC_SITE_URL
• Convex SITE_URL (Production)

Then redeploy.

Note:

• Current setup wizard auto-detects this mismatch and offers to fix/redeploy for you.