ChatRAG

Troubleshooting

Common issues and solutions for ChatRAG setup, configuration, and operation.

RAG System Issues

RAG Not Using Documents

Symptoms:

  • AI doesn't reference uploaded documents
  • Responses don't include document content

Solutions:

  1. Verify {{context}} is in RAG_SYSTEM_PROMPT
  2. Check embeddings were generated (OpenAI API key configured)
  3. Verify document_chunks table has data in Supabase
  4. Run diagnostic: node scripts/rag/check-rag-flow.js
  5. Check system prompt: node scripts/rag/decode-rag-prompt.js

Slow Search Performance

Solutions:

  • Verify HNSW indexes exist in Supabase (m=64, ef=200)
  • Check index parameters in complete_setup.sql
  • Use text-embedding-3-small for embeddings
  • Reduce RAG_FINAL_RESULT_COUNT if too high
  • Enable RAG_CACHE_ENABLED=true

Document Upload Failing

Solutions:

  • Check NEXT_PUBLIC_LLAMA_CLOUD_API_KEY is set
  • Verify LlamaCloud API key is valid
  • Check file format is supported (PDF, DOCX, TXT, HTML, RTF, EPUB)
  • Ensure Supabase storage buckets exist
  • Check browser console for errors

Database Issues

Database Connection Failed

Solutions:

  • Verify NEXT_PUBLIC_SUPABASE_URL is correct
  • Check NEXT_PUBLIC_SUPABASE_ANON_KEY is set
  • Ensure SUPABASE_SERVICE_ROLE_KEY is configured
  • Verify Supabase project is not paused
  • Check network connectivity to Supabase

Tables or Functions Missing

Solutions:

  • Run complete_setup.sql in Supabase SQL Editor
  • Check for SQL execution errors in editor
  • Verify pgvector extension is enabled
  • Ensure all 14 tables were created
  • Check HNSW indexes exist on document_chunks

Configuration Issues

Configuration Not Saving

Solutions:

  • Verify SUPABASE_SERVICE_ROLE_KEY is set
  • Check admin_settings table exists in Supabase
  • Ensure .env.local file is writable
  • Restart dev server after saving
  • Check Config UI console for errors

Models Not Appearing

Solutions:

  • Verify JSON syntax in all 5 model locations
  • Clear browser localStorage
  • Restart dev server
  • Check browser console for parsing errors
  • Use Config UI to re-fetch models from OpenRouter

Config UI Not Loading

Solutions:

  • Ensure port 3333 is not in use
  • Check scripts/config-server.js exists
  • Verify Node.js 18+ is installed
  • Run npm install to ensure dependencies
  • Check terminal for error messages

WhatsApp Integration Issues

QR Code Not Generating

Solutions:

  • Verify Bailey's is deployed at FLYIO_BAILEYS_URL
  • Check Fly.io app status: flyctl status
  • View logs: flyctl logs
  • Restart app: flyctl apps restart
  • Verify WHATSAPP_PROVIDER is set correctly

Messages Not Reaching ChatRAG

Solutions:

  • Verify WHATSAPP_WEBHOOK_URL is publicly accessible
  • Check webhook secret matches on both sides
  • Test webhook: curl https://your-webhook/api/whatsapp/webhook
  • Use ngrok for local development webhooks
  • Check ChatRAG logs for webhook errors

Connection Keeps Dropping

Solutions:

  • Verify persistent volume is mounted in Fly.io
  • Check app isn't sleeping (scale to prevent auto-sleep)
  • Ensure phone has stable internet
  • Don't logout of WhatsApp Web on other devices
  • Check session data is being persisted

MCP Integration Issues

Tools Not Appearing

Solutions:

  • Verify NEXT_PUBLIC_MCP_SYSTEM_ENABLED=true
  • Check MCP endpoint URL is correct
  • Click "Discover Tools" in Config UI
  • Check browser console for connection errors
  • Test server health endpoint

Tool Execution Fails

Solutions:

  • Verify authentication credentials are correct
  • Check server health and availability
  • Review approval prompt for parameter issues
  • Check MCP server logs for errors
  • Test tool individually before workflows

API & Authentication Issues

API Key Invalid

Solutions:

  • Verify keys are correctly formatted (no extra spaces)
  • Check for missing characters when copying
  • Ensure keys have necessary permissions
  • Regenerate keys if compromised
  • Check provider dashboard for key status

Authentication Not Working

Solutions:

  • Update NEXT_PUBLIC_SITE_URL to correct URL
  • Add redirect URLs in Supabase Auth settings
  • Check OAuth provider callback URLs
  • Verify email configuration
  • Check Supabase Auth logs

Debug Commands

Check Environment

cat .env.local

Test Database

Start dev server and check browser console for database errors

Check RAG Flow

node scripts/rag/check-rag-flow.js

Decode RAG Prompt

node scripts/rag/decode-rag-prompt.js

Fly.io Logs

flyctl logs

Fly.io Status

flyctl status

Performance Issues

Slow Response Times

Solutions:

  • Use faster models (GPT-4o-mini vs GPT-4)
  • Reduce max tokens setting
  • Enable RAG caching
  • Optimize chunk retrieval count
  • Use WhatsApp-optimized prompts for mobile

High API Costs

Solutions:

  • Switch to cost-effective models
  • Reduce WHATSAPP_MAX_TOKENS
  • Limit reasoning token usage
  • Use free tier models for testing
  • Enable usage alerts in provider dashboards
← Previous: DeploymentNext: FAQ →