Troubleshooting

Quick solutions to common issues. Most problems are related to environment variables, Convex configuration, or email setup.

Quick Fixes

Before diving into specific issues, try these first:

1. Restart the dev server: Stop and restart npm run dev
2. Restart Convex: Stop and restart npx convex dev
3. Clear browser cookies: Especially for auth issues
4. Check environment variables: Ensure all are set correctly
5. Check Convex dashboard: Look for errors in function logs

Authentication Issues

Can't Sign In

Symptoms:

• Login form submits but nothing happens
• Error messages about invalid credentials
• Redirect loops

Solutions:

1. Check email verification:

   • Users must verify their email before signing in
   • Check if verification email was sent
   • Try resending verification email

2. Verify Convex connection:

   npx convex dev

   Ensure Convex is running and connected.

3. Check BETTER_AUTH_SECRET:

   • Must be the same in .env.local and Convex
   • Generate a new one if unsure:

   openssl rand -base64 32

4. Check BETTER_AUTH_URL:

   • Must match your actual URL
   • For local: http://localhost:3000
   • For production: https://yourdomain.com

5. Clear cookies and try again:

   • Open DevTools → Application → Cookies
   • Delete all cookies for your domain
   • Try signing in again

Session Issues

Symptoms:

• Getting logged out unexpectedly
• Session not persisting
• "Unauthorized" errors

Solutions:

1. Check cookie settings:

   • Cookies require HTTPS in production
   • Ensure BETTER_AUTH_URL uses correct protocol

2. Verify secret consistency:

   • BETTER_AUTH_SECRET must match everywhere
   • If you changed it, all existing sessions are invalid

3. Check session expiration:

   • Sessions expire after configured time
   • Users need to sign in again after expiration

2FA Not Working

Symptoms:

• TOTP codes rejected
• "Invalid code" errors
• Can't complete 2FA setup

Solutions:

1. Check device time:

   • TOTP codes are time-based
   • Device clock must be accurate
   • Enable automatic time sync

2. Try backup codes:

   • Each backup code works once
   • 12 codes are generated during setup

3. Wait for next code:

   • Codes refresh every 30 seconds
   • If timing is close, wait for next code

4. Re-setup 2FA:

   • Disable and re-enable 2FA
   • Scan QR code again
   • Save new backup codes

Passkeys Not Working

Symptoms:

• Can't register passkey
• Passkey authentication fails
• "Origin mismatch" errors

Solutions:

1. Check PASSKEY_RP_ID:

   • Must match your domain exactly
   • No protocol (just yourdomain.com)
   • For local: use localhost

2. Ensure HTTPS:

   • Passkeys require HTTPS (except localhost)
   • Check SSL certificate is valid

3. Check browser support:

   • Use Chrome, Safari, Firefox, or Edge
   • Must be recent version
   • WebAuthn must be enabled

4. Check device settings:

   • Biometrics must be enabled
   • Device must support WebAuthn

Email Issues

Emails Not Sending

Symptoms:

• No verification email received
• Password reset email not arriving
• Invitation emails failing

Solutions:

1. Check Resend API key:

   npx convex env set RESEND_API_KEY "re_your_key"

2. Verify EMAIL_FROM:

   • Must use verified domain
   • Format: "Name <email@domain.com>"

3. Check Resend dashboard:

   • View sent emails
   • Check for errors
   • Verify domain status

4. Check spam folder:

   • Verification emails often land in spam
   • Mark as "not spam" to improve delivery

5. Test mode limitations:

   • In test mode, only verified emails receive mail
   • Use your own verified email for testing

Emails Going to Spam

Solutions:

1. Verify your domain:

   • Add DNS records in Resend
   • Wait for verification (can take hours)

2. Configure SPF/DKIM/DMARC:

   • Resend provides these records
   • Add all required DNS entries

3. Use proper sender address:

   • Use subdomain like mail.yourdomain.com
   • Avoid generic addresses

4. Warm up your domain:

   • Start with low volume
   • Gradually increase sending

Convex Issues

Connection Failed

Symptoms:

• "Failed to connect to Convex"
• Real-time updates not working
• Queries returning undefined

Solutions:

1. Check Convex is running:

   npx convex dev

2. Verify Convex URLs:

   CONVEX_DEPLOYMENT="dev:your-deployment"
   NEXT_PUBLIC_CONVEX_URL="https://your-deployment.convex.cloud"
   NEXT_PUBLIC_CONVEX_SITE_URL="https://your-deployment.convex.site"

3. Check Convex dashboard:

   • Login to dashboard.convex.dev
   • Verify deployment exists
   • Check for errors in logs

4. Reinstall Convex:

   npm install convex
   npx convex dev

Schema Errors

Symptoms:

• "Schema validation failed"
• Type errors in Convex functions
• Deployment fails

Solutions:

1. Check schema.ts:

   • Ensure all fields have valid types
   • Check for syntax errors

2. Run type check:

   npx convex dev

   Convex validates schema on startup.

3. Reset and redeploy:

   npx convex deploy --yes

Function Errors

Symptoms:

• Queries/mutations failing
• Error messages in console
• Unexpected behavior

Solutions:

1. Check Convex logs:

   • Open Convex dashboard
   • Go to Logs section
   • Find the failing function

2. Add error handling:

   export const myFunction = query({
     handler: async (ctx) => {
       try {
         // Your code
       } catch (error) {
         console.error("Function failed:", error);
         throw error;
       }
     },
   });

3. Test locally first:

   • Use Convex dashboard to test functions
   • Check input arguments

Environment Variable Issues

Variable Not Found

Symptoms:

• "Environment variable undefined"
• Features not working
• Deployment errors

Solutions:

1. Check .env.local exists:

   ls -la .env.local

2. Verify variable names:

   • Case-sensitive
   • No spaces around =
   • No quotes issues

3. Restart dev server:

   • Environment changes require restart
   • Stop and restart npm run dev

4. Set in Convex:

   npx convex env set VARIABLE_NAME "value"

5. Check which env file is loaded:

   • .env.local for development
   • Vercel/platform env for production

Secret Mismatch

Symptoms:

• Auth randomly failing
• "Invalid token" errors
• Sessions not working

Solutions:

1. Sync secrets:

   • BETTER_AUTH_SECRET must be identical in:
     • .env.local
     • Convex environment
     • Production environment

2. Generate new secret:

   openssl rand -base64 32

   Update everywhere.

3. Clear all sessions:

   • Old sessions won't work with new secret
   • Users need to sign in again

Build Issues

Build Fails

Symptoms:

• npm run build fails
• TypeScript errors
• Module not found

Solutions:

1. Check TypeScript errors:

   npx tsc --noEmit

2. Install dependencies:

   rm -rf node_modules
   npm install

3. Clear Next.js cache:

   rm -rf .next
   npm run build

4. Check import paths:

   • Use @/ alias correctly
   • Ensure files exist

Production Deployment Fails

Solutions:

1. Check all env vars are set:

   • In Vercel dashboard
   • For production environment

2. Match local build:

   npm run build

   Fix any errors locally first.

3. Check Vercel logs:

   • Deployment logs show errors
   • Function logs show runtime errors

Organization Issues

Can't Create Organization

Solutions:

1. Check user is authenticated:

   • Must be logged in
   • Email must be verified

2. Check Autumn is configured:

   • AUTUMN_API_KEY must be set
   • Or billing must be removed

Can't Add Members

Solutions:

1. Check Pro plan:

   • Organization must be on Pro plan
   • Upgrade first, then add members

2. Check permissions:

   • Only owners and admins can add members
   • Verify user role

3. Check billing status:

   • Subscription must be active
   • No payment failures

Invitations Not Working

Solutions:

1. Check email is sending:

   • Verify Resend is configured
   • Check Resend logs

2. Check invitation status:

   • View in organization dashboard
   • Resend if needed

3. Check user account:

   • Invitee may need to create account first
   • Email must match invitation

Admin Panel Issues

Can't Access Admin

Solutions:

1. Check admin role:

   • User must have admin role
   • Set in Convex dashboard

2. Set first admin:

   • Go to Convex dashboard
   • Navigate to betterAuth → users
   • Edit your user's role to admin

User Actions Failing

Solutions:

1. Check permissions:

   • Can't ban yourself
   • Can't impersonate other admins
   • Can't delete your own account

2. Check user exists:

   • User may have been deleted
   • Refresh the page

Performance Issues

Slow Page Loads

Solutions:

1. Check Convex queries:

   • Avoid fetching too much data
   • Use indexes for filters

2. Use pagination:

   • Don't load all records at once
   • Implement cursor-based pagination

3. Check network:

   • Slow connection affects real-time updates
   • Check Convex region is close to users

Memory Issues

Solutions:

1. Check for memory leaks:

   • Monitor with DevTools
   • Check for unsubscribed listeners

2. Optimize images:

   • Use Next.js Image component
   • Compress large images

Getting More Help

If you're still stuck:

1. Check logs:

   • Browser console
   • Convex dashboard logs
   • Vercel deployment logs

2. Search documentation:

   • Convex Docs
   • better-convex Docs - Our Better Auth + Convex integration
   • Better Auth Docs
   • Next.js Docs

3. Common error messages:

   • Search the exact error message
   • Check GitHub issues for the libraries

4. Contact support:

   • Provide detailed error messages
   • Include relevant configuration
   • Describe steps to reproduce