Docs / Troubleshooting

Troubleshooting Guide

Solutions to common issues with WooAI Chatbot Pro. Find your problem below and follow the step-by-step fix.

🔧 Quick Debug Checklist

Before diving into specific issues, run through this checklist:

  • Plugin is activated and license is valid
  • AI provider API key is configured and tested
  • Browser console shows no JavaScript errors
  • Server PHP version is 7.4 or higher
  • WordPress and WooCommerce are up to date
  • Caching plugins are cleared after changes

Widget Issues

❌ Chat widget not appearing on frontend
Possible Causes:
  • Widget is disabled in settings
  • Current page is in "Hide on Pages" list
  • JavaScript conflict with theme or other plugins
  • Ad blocker is blocking the widget script
✓ Solution:
  1. Go to WooAI Chat → Settings and verify "Enable Widget" is ON
  2. Check "Hide on Pages" setting - remove current page if listed
  3. Open browser console (F12) and look for JavaScript errors
  4. Disable ad blocker temporarily to test
  5. Try switching to a default WordPress theme (Twenty Twenty-Four)
  6. Deactivate other plugins one by one to find conflicts
❌ Widget appears but clicking does nothing
Possible Causes:
  • JavaScript not fully loaded
  • CSS z-index conflict (something covering the widget)
  • Event handlers not attaching properly
✓ Solution:
  1. Wait for page to fully load before clicking
  2. Check browser console for errors
  3. Inspect the widget element - look for overlapping elements
  4. Add this custom CSS: .wooai-chat-launcher { z-index: 999999 !important; }
  5. Clear all caches and hard refresh (Ctrl+Shift+R)
❌ Widget position is wrong or overlapping content
Possible Causes:
  • Theme has fixed elements in the same position
  • Offset values need adjustment
  • Other floating widgets (like cookie notices) conflicting
✓ Solution:
  1. Go to WooAI Chat → Appearance
  2. Try changing position from Bottom Right to Bottom Left (or vice versa)
  3. Increase offset values (try 30-50px instead of 20px)
  4. Use custom CSS to fine-tune position if needed

AI Provider Issues

❌ "Invalid API Key" error
Possible Causes:
  • API key was copied incorrectly (extra spaces)
  • API key has been revoked or expired
  • Using wrong type of key (service key vs. public key)
✓ Solution:
  1. Go to your AI provider's dashboard and generate a new API key
  2. Copy the key carefully - no spaces before or after
  3. For Gemini: Use key from Google AI Studio (not Google Cloud)
  4. For OpenAI: Key should start with sk-
  5. For Claude: Key should start with sk-ant-
  6. Paste the new key and save settings
  7. Use "Test Connection" button to verify
❌ "Rate limit exceeded" error
Possible Causes:
  • Too many requests in a short time
  • Exceeded monthly/daily quota
  • Free tier limits reached
✓ Solution:
  1. Wait 1-2 minutes and try again
  2. Check your provider's usage dashboard for quota status
  3. Configure a fallback provider in WooAI settings
  4. Consider upgrading to a paid tier for higher limits
  5. For Gemini free tier: 60 requests/minute limit
❌ Very slow responses (10+ seconds)
Possible Causes:
  • Using a slow/heavy AI model
  • Large system prompt or context
  • RAG search taking too long
  • Network issues between your server and AI provider
✓ Solution:
  1. Switch to a faster model: gemini-1.5-flash or gpt-4o-mini
  2. Reduce system prompt length (keep under 500 words)
  3. In RAG settings, reduce "Max Results" to 3
  4. Increase similarity threshold to reduce search time
  5. Test AI directly via provider's console to isolate network issues
❌ AI gives wrong or generic answers about products
Possible Causes:
  • RAG is not configured or disabled
  • Products not indexed in Supabase
  • Similarity threshold too high (missing results)
  • Product descriptions are too short
✓ Solution:
  1. Go to WooAI Chat → RAG & Search and verify it's enabled
  2. Check the indexed product count - should match your catalog
  3. Click "Reindex All Products" to refresh the index
  4. Lower similarity threshold to 0.6 for more results
  5. Add more detailed product descriptions in WooCommerce

RAG & Supabase Issues

❌ "Failed to connect to Supabase" error
Possible Causes:
  • Incorrect Supabase URL or API key
  • Supabase project is paused (free tier inactivity)
  • Server firewall blocking outbound connections
✓ Solution:
  1. Verify Supabase URL format: https://xxxxx.supabase.co
  2. Use the anon (public) key, not service_role
  3. Log into Supabase and check if project is paused - restore if needed
  4. Contact your host if firewall is blocking port 443 outbound
❌ Product indexing fails or hangs
Possible Causes:
  • PHP timeout for large catalogs
  • Memory limit exceeded
  • Supabase rate limits hit
✓ Solution:
  1. Increase PHP max_execution_time to 300 in php.ini
  2. Increase PHP memory_limit to 256M or higher
  3. For large catalogs (1000+), index in batches using WP-CLI: 
    wp wooai index-products --batch=100
  4. Wait a few minutes between large batches
❌ Search returns no results or wrong products
Possible Causes:
  • Products not indexed or partially indexed
  • Similarity threshold too high
  • Product descriptions don't match search terms
✓ Solution:
  1. Use the "Test Search" feature in RAG settings
  2. Lower similarity threshold to 0.5 temporarily for testing
  3. Click "Reindex All Products" to refresh
  4. Add relevant keywords to product descriptions
  5. Include common synonyms (e.g., "running shoes", "jogging sneakers")

License Issues

❌ License activation fails
Possible Causes:
  • License key copied incorrectly
  • License already used on another site
  • Server cannot reach license server
✓ Solution:
  1. Copy license key again from your purchase email
  2. Ensure no extra spaces before/after the key
  3. If transferring from another site, deactivate there first
  4. Check that your server allows outbound HTTPS connections
  5. Contact support if you need to reset your activation

Performance Issues

❌ Website slows down after installing plugin
Possible Causes:
  • Plugin conflict causing PHP slowdown
  • Database queries not optimized
  • Caching not configured properly
✓ Solution:
  1. WooAI widget loads asynchronously - should not affect page load
  2. If slow in admin, check for plugin conflicts
  3. Enable object caching (Redis/Memcached) if available
  4. Use Query Monitor plugin to identify slow queries
  5. Contact support with performance data if issue persists

Enable Debug Mode

For advanced troubleshooting, enable debug mode to see detailed logs:

WordPress Debug Log

Add these lines to your wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Logs will be saved to /wp-content/debug.log

WooAI Debug Mode

Enable in WooAI settings:

  1. Go to WooAI Chat → Settings → Advanced
  2. Enable "Debug Mode"
  3. Reproduce the issue
  4. Check debug.log for WooAI-specific entries
⚠️ Disable in Production

Remember to disable debug mode on production sites. Debug logs can contain sensitive information and may impact performance.

Server Requirements Check

Verify your server meets minimum requirements:

PHP Version: 7.4+ (8.0+ recommended)
WordPress: 6.0+
WooCommerce: 7.0+
Memory Limit: 128M+ (256M recommended)
Max Execution Time: 60+ seconds
cURL: Enabled with SSL
OpenSSL: 1.0.1+

Check your configuration in WordPress: Tools → Site Health → Info

Still stuck?

If you've tried the solutions above and still have issues, our support team is here to help.

When contacting support, please include: WordPress version, WooCommerce version, PHP version, error messages, and steps to reproduce.

Contact Support
← FAQ Back to Docs Home →