Nexfolio docsBack to site

Guide 3 of 4

Troubleshooting

Fixes for common problems

Most problems fall into one of two buckets: the database isn't connected yet, or your site's URL and the URL auth expects don't match.

Publishing

The first build failed

Expected. When you create the project the database doesn't exist yet, so the build has nothing to connect to.

Add the database — Storage → Create Database → Convex → Free plan → Connect — then Deployments → Redeploy.

The build fails with Invalid Convex deploy key (401)

CONVEX_DEPLOY_KEY is missing or wrong for the environment being built.

  1. Project → Storage — is a Convex database connected?
  2. Project → Settings → Environment Variables — is CONVEX_DEPLOY_KEY present, and does it cover the environment that failed?

A common case: the key exists for Production but not Preview, so production deploys fine and preview branches fail. Either connect the database to Preview as well, or turn preview deployments off.

The build fails and there's no CONVEX_DEPLOY_KEY at all

The Marketplace integration didn't finish connecting. Re-run Storage → Create Database → Convex, and make sure you complete the final Connect a Project step with Production ticked.

SITE_URL is not set in Convex / BETTER_AUTH_SECRET is not set

scripts/bootstrap-convex-env.mjs sets both on the first deploy. If you see this, it couldn't write to Convex — check the build log for a line starting with [bootstrap-convex-env] WARNING.

Usually the deploy key lacks permission. You can also set them by hand: Convex dashboard → your production deployment → Environment Variables → SITE_URL = https://your-site.vercel.app and a BETTER_AUTH_SECRET of 32+ characters.

Both must be set. Setting only one makes auth fail on purpose, with a clearer error than a half-configured login would give you.

Logging in

Invalid origin, redirect loops, or login silently fails

The SITE_URL stored in Convex doesn't match the address you're browsing.

This is almost always a custom domain that was added in Vercel without updating Convex. Fix both sides:

  1. Vercel → Settings → Environment Variables → NEXT_PUBLIC_SITE_URL = https://yourdomain.com (Production)
  2. Convex dashboard → production deployment → Environment Variables → SITE_URL = https://yourdomain.com
  3. Redeploy in Vercel

No trailing slash, and include https://.

/admin/seed says the account already exists

You already created it. Go to /admin and log in. Forgotten the password? See below.

I moved my site to a new database and now I can't log in

Carry your BETTER_AUTH_SECRET across. If you restore a backup into a new Convex deployment, the deployment generates a fresh auth secret on its first build — but your restored auth records were encrypted with the old one, so login fails even though your password is correct.

Fix: Convex dashboard → the new deployment → Environment Variables → set BETTER_AUTH_SECRET to the value from the old deployment. It takes effect immediately; no redeploy needed.

Note that /admin/seed won't rescue you here — if you'd disabled the seed route before the backup, that setting comes across too.

To rotate the secret afterwards, do it in this order: sign in, change your password, delete the rows in the betterAuth component's jwks table, then set a new BETTER_AUTH_SECRET. Better Auth regenerates the keys against the new secret. Changing the secret without clearing jwks locks you out.

I've locked myself out of the admin

If the seed route is still enabled, open /admin/seed and create the account again. If you disabled it, re-enable it temporarily by editing the settings table in the Convex dashboard, then create the admin and turn it back off.

Content and images

Images don't appear

Images are stored in Convex file storage and served from *.convex.cloud. If they're broken, the site is pointing at a different Convex deployment than the one holding the files — most often after moving the project between Convex deployments. Check NEXT_PUBLIC_CONVEX_URL in the build log.

I seeded demo content and lost my own

Seeding is destructive and can't be undone from the app. If you have a Convex backup from before, restore it from the Convex dashboard. Otherwise the content is gone — this is why the button sits in a Danger zone behind a confirmation.

Local development

npm run dev fails, or auth won't initialise locally

Your Convex development deployment needs its own settings — they're separate from production:

npx convex env set SITE_URL http://localhost:3000
npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"

The secret must match BETTER_AUTH_SECRET in .env.local. npm run setup does all of this for you.

No CONVEX_DEPLOYMENT set

Run npx convex dev --once. It creates the dev deployment and writes the values into .env.local.

Still stuck

Check the Vercel build log first — it shows exactly which values were derived:

[bootstrap-convex-env] Set SITE_URL=...
✔ Ran "npm run build" with environment variables "NEXT_PUBLIC_CONVEX_URL" ... set
✔ Deployed Convex functions to https://....convex.cloud

If those three lines are present, the configuration worked and the problem is elsewhere. See install.md for where each setting comes from.