Troubleshooting Guide

Quick Diagnostic Commands

Start with these commands to diagnose most issues:

# Check code quality (must pass with zero errors)
pnpm lint && pnpm typecheck

# Check environment setup
npx convex status
npx convex env list

# Monitor live logs
npx convex logs --tail

# Check external services
# Check Stripe webhook delivery in Stripe Dashboard

Development Issues

Build and Compilation Errors

TypeScript Compilation Errors

Symptoms: pnpm typecheck fails with TypeScript errors

# Clear caches and regenerate types
rm -rf .next && rm -rf node_modules/.cache
npx convex codegen
pnpm typecheck

Common Causes:

Outdated generated types from Convex
Missing dependencies after updates
Type conflicts between packages

ESLint Errors

Symptoms: pnpm lint fails with linting errors

# Fix auto-fixable issues
pnpm lint --fix

# For stubborn issues, check specific rules
pnpm lint --debug

Common Issues:

Unused imports/variables
Incorrect import ordering
Missing dependency arrays in useEffect

Build Failures

Symptoms: pnpm build or pnpm dev fails

# Clear Next.js cache
rm -rf .next

# Clear pnpm cache
pnpm store prune

# Reinstall dependencies
rm -rf node_modules
pnpm install

Database and Convex Issues

Connection Problems

Symptoms: "Failed to connect to Convex" errors

# Check Convex status
npx convex status

# Reset authentication
npx convex logout
npx convex login

# Check environment variables
echo $CONVEX_DEPLOYMENT
echo $NEXT_PUBLIC_CONVEX_URL

Solutions:

Verify CONVEX_DEPLOYMENT and NEXT_PUBLIC_CONVEX_URL are correct
Ensure Convex project is deployed and active
Check network connectivity

Schema Issues

Symptoms: Database queries failing, missing tables

# Check current schema
npx convex dashboard
# Navigate to "Data" tab to see tables

# Push schema changes
npx convex dev  # Automatically pushes schema changes

# If needed, regenerate types
npx convex codegen

Function Errors

Symptoms: Convex function calls failing

# Monitor function logs
npx convex logs --tail | grep "error\|Error"

# Check specific function
npx convex logs --tail | grep "functionName"

Common Issues:

Permission checks failing
Invalid arguments passed to functions
Database constraints violated
Network issues during external API calls

Authentication Issues

OAuth Not Working

Symptoms: OAuth login fails or redirects incorrectly

GitHub OAuth:

# Verify callback URL in GitHub OAuth app
# Should be: http://localhost:3001/api/auth/callback/github (dev)
# Should be: https://yourdomain.com/api/auth/callback/github (prod)

Google OAuth:

# Check authorized redirect URIs in Google Cloud Console
# Should match your domain exactly

Solutions:

Verify OAuth app credentials in .env.local
Check callback URLs match your domain
Ensure OAuth apps are enabled and approved

Password Reset Issues

Symptoms: Password reset emails not sending

# Check Convex environment variables
npx convex env list | grep RESEND

# Check email configuration in admin panel
# Go to /admin → Site Settings → Email Configuration

Solutions:

Verify RESEND_API_KEY is set in Convex environment: npx convex env set RESEND_API_KEY re_...
Check email configuration in admin panel under "Site Settings → Email Configuration"
Verify Resend API key is valid and active
Ensure support email, domain, and site URL are configured in database

See Environment Variables Reference for complete configuration.

Session Issues

Symptoms: Users getting logged out frequently

# Check authentication logs
npx convex logs --tail | grep "auth\|session"

Solutions:

Verify JWT configuration in Convex Auth
Check session timeout settings
Ensure consistent domain configuration

Stripe Integration Issues

Webhook Problems

Symptoms: Stripe events not processed, subscription status not updating

# Check webhook delivery in Stripe Dashboard:
# Developers > Webhooks > [your endpoint] > Recent deliveries

# Check webhook signing secret is set in Convex
npx convex env list | grep STRIPE_WEBHOOK_SECRET

Solutions:

Verify webhook URL is accessible from Stripe's servers
Check STRIPE_WEBHOOK_SECRET matches the endpoint secret
Ensure webhook endpoint is configured with correct events

Payment Issues

Symptoms: Checkout not working, payments failing

# Check Stripe backend keys (Convex environment)
# Note: STRIPE_PUBLISHABLE_KEY is not needed - Stripe operations use Convex backend actions
npx convex env get STRIPE_SECRET_KEY | head -c 8  # Should start with sk_test_ or sk_live_
npx convex env get STRIPE_WEBHOOK_SECRET | head -c 8  # Should start with whsec_

# Test API connectivity
stripe customers list --limit 1

Solutions:

Verify API keys are correct and match environment (test/live)
Check Stripe account is active and in good standing
Ensure Customer Portal is configured

Product Sync Issues

Symptoms: Products not appearing, sync failing

# Check product sync status
# Go to /admin/products in your application

# Monitor sync logs
npx convex logs --tail | grep "product\|stripe"

Solutions:

Use admin interface to sync products from Stripe
Verify Stripe API keys have correct permissions
Check seed file exists at /convex/seeds/stripe_products.ts

Email System Issues

Email Not Sending

Symptoms: Notifications, invitations, or password reset emails not delivered

# Check Resend configuration
npx convex env list | grep RESEND
echo $RESEND_API_KEY

# Check Resend dashboard
# Visit resend.com/emails to see delivery status

Notification System Issues:

# Check Convex environment (for notifications)
npx convex env get RESEND_API_KEY
npx convex env get RESEND_TEST_MODE

# Check email configuration in admin panel
# Go to /admin → Site Settings → Email Configuration

Password Reset Issues:

# Check local environment (for password reset)
echo $RESEND_API_KEY

# Check email configuration in admin panel
# Go to /admin → Site Settings → Email Configuration
# Verify: Support Email, Support Email Name, Resend Domain, Site URL

Solutions:

Verify API keys are valid and active
Check email configuration in admin panel ("Site Settings → Email Configuration")
Ensure you're not hitting rate limits
For production, verify domain is configured in Resend
Verify all required fields are set: Support Email, Support Email Name, Resend Domain, Site URL

Test Mode Issues

Symptoms: Emails going to real users instead of test addresses

Solutions:

Verify you're using test email addresses (delivered@resend.dev)
Check notification form shows test mode indicators
Ensure development environment is correctly configured

Real-time Features Issues

Chat Not Updating

Symptoms: Messages not appearing in real-time

# Check WebSocket connection
# Open browser dev tools → Network → WS tab

# Check message queries
npx convex logs --tail | grep "messages"

Solutions:

Verify Convex connection is active
Check user has proper team permissions
Ensure team ID is correct in queries

Notifications Not Appearing

Symptoms: In-app notifications not showing

# Check notification queries
npx convex logs --tail | grep "notification"

# Verify user permissions
# Check admin role for notification sending

Solutions:

Verify user is authenticated and has team access
Check notification targeting is correct
Ensure real-time subscriptions are working

Performance Issues

Slow Page Loads

Symptoms: Pages loading slowly, poor Core Web Vitals

# Analyze bundle size
pnpm build
npx @next/bundle-analyzer

# Check for large dependencies
# Use browser dev tools → Network tab

Solutions:

Optimize images using Next.js Image component
Implement code splitting for large components
Check for unnecessary re-renders with React DevTools
Use dynamic imports for heavy components

Database Query Performance

Symptoms: Slow queries, timeouts

# Monitor query performance
npx convex dashboard
# Check "Functions" tab for slow queries

# Check for missing indexes
npx convex logs --tail | grep "slow\|timeout"

Solutions:

Add appropriate indexes to schema
Use .withIndex() instead of .filter() for queries
Implement pagination for large result sets
Optimize query patterns

Production Issues

Deployment Failures

Symptoms: Vercel deployment fails

# Check build logs in Vercel dashboard
# Common issues:
# - TypeScript errors
# - ESLint errors
# - Missing environment variables

Solutions:

Run pnpm lint && pnpm typecheck locally first
Verify all environment variables are set in Vercel
Check build settings match local development

Environment Configuration

Symptoms: Features not working in production

Common Missing Variables:

# Vercel environment variables checklist:
CONVEX_DEPLOYMENT=prod:your-project
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
NEXT_PUBLIC_SITE_URL=https://yourdomain.com

# Convex environment variables (backend-only):
# npx convex env set STRIPE_SECRET_KEY sk_live_...
# npx convex env set STRIPE_WEBHOOK_SECRET whsec_production...
# Note: Email configuration is managed via admin panel
# Note: STRIPE_PUBLISHABLE_KEY is not needed - Stripe uses backend actions

Solutions:

Verify all production environment variables are set
Check OAuth callback URLs match production domain
Ensure Stripe webhook endpoints point to production

SEO and OG Images

Symptoms: OG images not displaying, sitemap not accessible

# Test OG images
curl -I https://yourdomain.com/opengraph-image

# Test sitemap
curl https://yourdomain.com/sitemap.xml

# Test robots.txt
curl https://yourdomain.com/robots.txt

Solutions:

Verify Convex HTTP endpoint is deployed (check npx convex deploy succeeded)
Ensure site branding is configured in admin settings

Security Issues

Permission Errors

Symptoms: Users can't access features they should have access to

# Check user roles
npx convex logs --tail | grep "permission\|role"

# Debug permission functions
# Add console.logs to permission checking functions

Solutions:

Verify user has correct role in database
Check team membership is active
Ensure permission checking functions are working correctly

Monitoring and Debugging

Comprehensive Debug Session

When facing complex issues, use this systematic approach:

# 1. Check all quality gates
pnpm lint && pnpm typecheck

# 2. Check environment
npx convex status
npx convex env list

# 3. Monitor live activity
npx convex logs --tail &

# 4. Test specific functionality
# Use your application and monitor logs

# 5. Check external services
# Visit Resend dashboard, Stripe dashboard

Performance Monitoring

# Monitor function performance
npx convex dashboard
# Check "Functions" tab for performance metrics

# Monitor bundle size
pnpm build && npx @next/bundle-analyzer

# Check Core Web Vitals
# Use Google PageSpeed Insights

Log Analysis

# Filter logs by category
npx convex logs --tail | grep "error\|Error"
npx convex logs --tail | grep "auth\|login"
npx convex logs --tail | grep "stripe\|billing"
npx convex logs --tail | grep "email\|notification"
npx convex logs --tail | grep "team\|member"

Getting Help

Before Asking for Help

Check this guide for your specific issue
Run diagnostic commands listed at the top
Check logs for specific error messages
Verify environment variables are correctly set
Test in a clean environment if possible

Information to Include

When seeking help, include:

Exact error messages from logs
Steps to reproduce the issue
Environment details (development/production)
Recent changes made to the codebase
Relevant configuration (environment variables, etc.)

Support Resources

Convex Discord: convex.dev/community
Stripe Support: support.stripe.com
Next.js Documentation: nextjs.org/docs
Vercel Support: vercel.com/support
TinyKit SaaS Documentation: Check other files in /docs folder

Remember: Most issues can be resolved by carefully checking environment variables, reviewing logs, and ensuring all quality gates pass (pnpm lint && pnpm typecheck).

Troubleshooting Guide

On this page