Skip to main content

Common Issues

Common problems and their solutions when working with AIQ.

Installation Issues​

Environment Variables Not Loading​

Symptom: Application crashes with "Environment variable not defined" errors.

Solution:

  1. Ensure .env.local exists in the project root (not in subdirectories)
  2. Restart the development server after adding environment variables
  3. Verify variable names match exactly (case-sensitive)
# Stop the server
Ctrl+C

# Restart
npm run dev

Database Connection Failed​

Symptom: "Failed to connect to Supabase" or timeout errors.

Solution:

  1. Check Supabase project status in dashboard
  2. Verify NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY are correct
  3. Check your internet connection
  4. Ensure RLS policies are applied:
npx supabase db push

Migration Errors​

Symptom: Migrations fail with constraint or syntax errors.

Solution:

  1. Check if migrations were already applied:
npx supabase migration list
  1. If stuck, reset and reapply:
# Be careful - this drops all data!
npx supabase db reset
npx supabase db push
  1. Check for migration file conflicts (duplicate timestamps)

API Key Issues​

Invalid API Key Format​

Symptom: Provider returns "Invalid API key" or authentication errors.

Solution:

  1. Verify key format matches provider requirements:

    • Anthropic: sk-ant-api03-... (80+ characters)
    • OpenAI: sk-... (51 characters)
    • Google: Alphanumeric, 39 characters
    • Perplexity: pplx-...

  2. Check for extra spaces, quotes, or newlines:

# Incorrect (has quotes)
ANTHROPIC_API_KEY="sk-ant-..."

# Correct (no quotes)
ANTHROPIC_API_KEY=sk-ant-...
  1. Regenerate key from provider dashboard if necessary

API Key Not Found in Settings​

Symptom: Settings page shows "No API keys configured".

Solution:

  1. Add keys through the Settings UI first
  2. Keys are encrypted and stored per organization
  3. Environment variable keys (ANTHROPIC_API_KEY etc.) are only used as fallback

Query Execution Issues​

Rate Limit Exceeded​

Symptom: Queries fail with "Rate limit exceeded" or 429 errors.

Solution:

  1. Slow down request rate - wait 1-2 seconds between queries

  2. Check provider dashboard for rate limits:

    • Anthropic Tier 1: 50 requests/minute
    • OpenAI Tier 1: 60 requests/minute
    • Gemini: 60 requests/minute (free tier)

  3. Upgrade API tier if needed for higher limits

Model Not Found (404)​

Symptom: "Model not found" or 404 errors when querying.

Solution:

  1. Check if model ID is current (models get deprecated):

    • ✅ Current: claude-sonnet-4-5-20250929
    • ❌ Deprecated: claude-3-5-sonnet-20241022

  2. Update lib/api/llm-client-factory.ts with valid model IDs

  3. Rebuild and redeploy

Timeout Errors​

Symptom: Queries timeout after 30-60 seconds.

Solution:

  1. Increase timeout in Vercel (Pro plan required for >60s)
  2. Simplify prompts - shorter prompts = faster responses
  3. Use faster models (e.g., claude-3-5-haiku-20241022 instead of opus)
  4. Check provider status pages for outages

UI/Display Issues​

Analytics Not Updating​

Symptom: Dashboard shows old data or "0 queries".

Solution:

  1. Hard refresh the page: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
  2. Check if queries actually executed (check Supabase dashboard)
  3. Verify RLS policies allow reads:
-- Run in Supabase SQL Editor
SELECT * FROM llm_queries LIMIT 10;
  1. Check browser console for errors (F12)

Dark Mode Issues​

Symptom: Text not visible or styling broken.

Solution:

  1. Ensure Tailwind CSS is configured correctly
  2. Check if dark: classes are applied
  3. Clear browser cache and reload
  4. Verify Tailwind config in tailwind.config.ts

Performance Issues​

Slow Page Load​

Symptom: Pages take 5+ seconds to load.

Solution:

  1. Check database query performance in Supabase dashboard
  2. Verify indexes are created (migrations should handle this)
  3. Limit large queries with pagination
  4. Enable Next.js caching for static content

High API Costs​

Symptom: Unexpected high bills from LLM providers.

Solution:

  1. Review query history in AIQ analytics
  2. Check for accidental batch executions
  3. Set spending limits in provider dashboards:
    • OpenAI: Billing → Usage Limits
    • Anthropic: Billing → Budget Alerts
  4. Use cheaper models for testing (Gemini free tier, or Perplexity)

Deployment Issues​

Vercel Build Fails​

Symptom: Deployment fails with TypeScript or build errors.

Solution:

  1. Check build logs for specific errors
  2. Verify all environment variables are set in Vercel
  3. Run build locally first:
npm run build
  1. Fix TypeScript errors before deploying
  2. Ensure all dependencies are in package.json

Environment Variables Not Working in Production​

Symptom: Works locally but fails in production.

Solution:

  1. Set environment variables in Vercel dashboard (Project Settings → Environment Variables)
  2. Redeploy after adding variables
  3. Use NEXT_PUBLIC_ prefix for client-side variables
  4. Check variable names match exactly (case-sensitive)

Data Issues​

Missing Citations​

Symptom: Queries execute but no citations are extracted.

Solution:

  1. Check if provider response actually contains citations
  2. Verify citation extraction logic in lib/utils/citation-extractor.ts
  3. Some providers (like base GPT-4) don't always include citations
  4. Use Perplexity for guaranteed citation-rich responses

Duplicate Queries in History​

Symptom: Same query appears multiple times.

Solution:

  1. Check if page is being refreshed/reloaded during execution
  2. Verify database constraints are applied
  3. Clear test data if needed:
DELETE FROM llm_queries WHERE prompt LIKE '%test%';

Getting More Help​

If you're still stuck:

  1. Check GitHub Issues: github.com/your-repo/issues
  2. Review Documentation: See other docs sections for detailed guides
  3. Check Provider Status:
  4. Review Logs:
    • Browser console (F12)
    • Vercel logs (if deployed)
    • Supabase logs (Database → Logs)