Troubleshooting Guide

Auth loops, embedding failures, Stripe mismatches, and the env typos we see when someone clones fresh on a new laptop.

Authentication Issues

"Unauthorized" on Dashboard

Symptoms: Redirected to login, 401 errors

Solutions:

  1. Check Supabase URL and keys in .env.local
  2. Clear browser cookies and re-login
  3. Verify RLS policies are correct
  4. Check session hasn't expired

OAuth Login Fails

Symptoms: Error after OAuth redirect

Solutions:

  1. Verify callback URL in Supabase matches:
    • https://xxxxx.supabase.co/auth/v1/callback
  2. Check OAuth provider settings (client ID, secret)
  3. Enable the provider in Supabase Auth settings
  4. Verify redirect URLs in OAuth app settings

Profile Not Created

Symptoms: User logged in but no profile

Solutions:

  1. Check trigger function exists: 
    SELECT * FROM pg_trigger WHERE tgname = 'on_auth_user_created';
  2. Run trigger creation SQL from schema.sql
  3. Manually insert profile for testing

Chat Issues

"Insufficient Credits" (402)

Symptoms: Can't send messages

Solutions:

  1. Check profile credits in Supabase
  2. Add credits manually for testing: 
    UPDATE profiles SET credits = 100 WHERE id = 'user-id';
  3. Verify credit calculation in credit-calculator.ts

Chat Messages Not Saving

Symptoms: Messages disappear on refresh

Solutions:

  1. Check RLS policies for messages table
  2. Verify chat_id is being passed correctly
  3. Check Supabase logs for insert errors
  4. Ensure user owns the chat

Streaming Not Working

Symptoms: Response appears all at once

Solutions:

  1. Check browser supports ReadableStream
  2. Verify toTextStreamResponse() is used
  3. Check for proxy/CDN buffering issues
  4. Try disabling response compression

Model Not Available

Symptoms: 403 on model selection

Solutions:

  1. Check user tier allows model
  2. Verify pricing.ts includes model in tier
  3. Update tier in database if needed

RAG Issues

Document Upload Fails

Symptoms: Upload errors, timeout

Solutions:

  1. Check file size (max 10MB)
  2. Verify MIME type is allowed
  3. Check Supabase Storage bucket exists
  4. Verify storage policies allow upload
  5. Check user folder path format

No RAG Results

Symptoms: AI ignores uploaded documents

Solutions:

  1. Check document status is "completed"
  2. Verify embeddings exist: 
    SELECT COUNT(*) FROM document_embeddings
WHERE document_id = 'doc-id';
  3. Check similarity threshold isn't too high
  4. Verify documentIds are passed to API
  5. Test with lower matchThreshold

Poor RAG Quality

Symptoms: Irrelevant or incomplete answers

Solutions:

  1. Increase defaultTopK for more context
  2. Adjust chunk size/overlap in config
  3. Improve document formatting (clear headings)
  4. Check embedding model is working
  5. Review system prompt template

Stripe Issues

Webhook Not Received

Symptoms: Payment succeeds but tier not updated

Solutions:

  1. Check webhook endpoint URL is correct
  2. Verify webhook signing secret
  3. Check Stripe Dashboard → Webhooks → Logs
  4. Test locally with Stripe CLI: 
    stripe listen --forward-to localhost:3000/api/webhooks/stripe

Webhook Signature Error

Symptoms: 400 error on webhook

Solutions:

  1. Use req.text() not req.json(): 
    const body = await req.text(); // Correct
  2. Verify STRIPE_WEBHOOK_SECRET is correct
  3. Check for whitespace in environment variable

Checkout Redirect Fails

Symptoms: Stuck on checkout or error

Solutions:

  1. Verify NEXT_PUBLIC_APP_URL is correct
  2. Check price ID exists and is active
  3. Verify Stripe API key is valid
  4. Check browser console for errors

Database Issues

RLS Policy Errors

Symptoms: Permission denied errors

Solutions:

  1. Verify policies exist: 
    SELECT * FROM pg_policies WHERE tablename = 'profiles';
  2. Re-run policy creation from schema.sql
  3. Check auth.uid() returns correct user ID

pgvector Errors

Symptoms: Embedding queries fail

Solutions:

  1. Enable extension: 
    CREATE EXTENSION IF NOT EXISTS vector;
  2. Verify embedding dimension matches (1536)
  3. Check index exists on embeddings column
  4. Rebuild index if corrupted

Connection Errors

Symptoms: "Connection terminated" errors

Solutions:

  1. Enable connection pooling in Supabase
  2. Reduce concurrent connections
  3. Check for connection leaks in code
  4. Verify database isn't paused (free tier)

Performance Issues

Slow Page Loads

Solutions:

  1. Check for N+1 query patterns
  2. Use parallel data fetching
  3. Add React Suspense boundaries
  4. Enable static generation where possible

High Token Usage

Solutions:

  1. Reduce maxTokens for responses
  2. Limit conversation history length
  3. Use cheaper models for simple tasks
  4. Implement token-aware truncation

Memory Issues

Solutions:

  1. Reduce chunk batch size for embeddings
  2. Stream large file processing
  3. Limit concurrent document processing
  4. Add pagination for large data sets

Development Issues

TypeScript Errors

Solutions:

  1. Run pnpm tsc --noEmit to check
  2. Update types in types/index.d.ts
  3. Ensure config types are exported correctly
  4. Check for missing dependencies

Build Failures

Solutions:

  1. Check all environment variables are set
  2. Verify Stripe client has fallback for build time
  3. Run pnpm build locally first
  4. Check for import cycles

Hot Reload Not Working

Solutions:

  1. Restart dev server
  2. Clear .next folder
  3. Check for file system case sensitivity issues
  4. Verify Turbopack is working

Getting Help

If issues persist:

  1. Check console logs (browser and server)
  2. Review Supabase logs
  3. Check Stripe webhook logs
  4. Search existing GitHub issues
  5. Create detailed bug report with:
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details
    • Relevant logs