Skip to main content

Troubleshooting

This comprehensive troubleshooting guide helps you resolve common issues with the FEL AI Product Advisor plugin.

Quick Diagnostics

Before diving into specific issues, try these general troubleshooting steps:

  1. Clear cache: bin/console cache:clear
  2. Rebuild assets: bin/build-storefront.sh
  3. Check browser console (F12) for JavaScript errors
  4. Verify OpenAI API status: https://status.openai.com

Chatbot Not Appearing​

Issue: Chatbot element not visible on the page​

Possible Causes & Solutions:

1. Plugin Not Activated​

Check:

# List installed plugins
bin/console plugin:list | grep FelAIProductAdvisor

Solution:

  1. Navigate to Settings → System → Plugins
  2. Find "FEL AI Product Advisor"
  3. Ensure toggle is activated (green)
  4. Clear cache: bin/console cache:clear

2. API Key Missing or Invalid​

Check:

  1. Navigate to Settings → Plugins → FEL OAI Assistants Manager
  2. Click "..." → Configuration
  3. Verify API key is entered
  4. Click "API Test" button to validate

Solution:

  • Obtain valid API key from OpenAI Platform
  • Re-enter the key and save
  • Test the connection

3. Assistant Not Selected​

Check:

  1. Edit the CMS page with the chatbot element
  2. Click on the chatbot element
  3. Verify "Assistent auswählen" field has a value

Solution:

  • Select a configured OpenAI Assistant from the dropdown
  • If no assistants available, create one in the base plugin first

4. Assets Not Compiled​

Check:

  • Browser console shows 404 errors for JS/CSS files
  • Chatbot appears broken or unstyled

Solution:

# Rebuild storefront assets
bin/build-storefront.sh

# Clear cache
bin/console cache:clear

5. Browser Cache Issues​

Solution:

  • Hard refresh: Ctrl + F5 (Windows) or Cmd + Shift + R (Mac)
  • Clear browser cache completely
  • Try incognito/private browsing mode

Chatbot Not Responding​

Issue: Chatbot displays but doesn't answer messages​

Possible Causes & Solutions:

1. OpenAI API Connection Issues​

Check:

  1. Browser console (F12) → Network tab
  2. Look for failed API requests to OpenAI
  3. Check response errors

Solution:

  • Verify API key is valid and has credits
  • Check OpenAI API status: https://status.openai.com
  • Ensure server can reach https://api.openai.com
  • Verify firewall/proxy allows outbound HTTPS

2. Insufficient OpenAI Credits​

Check:

  • Log into OpenAI Platform
  • Navigate to Billing → Usage
  • Verify account has available credits

Solution:

  • Add credits to OpenAI account
  • Set up payment method
  • Check spending limits

3. Assistant Configuration Error​

Check:

  1. Navigate to base plugin: FEL OAI Assistants Manager
  2. Verify Assistant is properly configured
  3. Check Assistant has necessary functions enabled

Solution:

  • Reconfigure Assistant in base plugin
  • Ensure required functions are activated
  • Test Assistant independently

4. JavaScript Errors​

Check:

  • Open browser console (F12)
  • Look for red error messages
  • Check for conflicts with other plugins

Solution:

# Rebuild administration
bin/build-administration.sh

# Rebuild storefront
bin/build-storefront.sh

# Clear all caches
rm -rf var/cache/*
bin/console cache:clear

Performance Issues​

Issue: Chatbot is very slow to respond​

Optimization Strategies:

1. Reduce Data Complexity​

Action:

  • Limit Categories: Exclude unnecessary categories in plugin settings
  • Filter Properties: Select only relevant property groups
  • Reduce Description Length: Lower max description length (default: 500)
  • Limit Search Results: Reduce search result limit (default: 8)

Configuration Location: Settings → Plugins → FEL AI Product Advisor → Configuration

2. Optimize API Settings​

Adjust in base plugin configuration:

SettingRecommended ValueImpact
Wartezeit (Sekunden)1-2Lower = faster, but may timeout
Max. Versuche30-40Lower = faster timeout
Caution

Don't set wait time below 1 second - may cause API errors!

3. Use Faster AI Model​

Model Performance Comparison:

ModelSpeedCostQuality
GPT-4o-mini⚡⚡⚡ Very Fast€ Very Low⭐⭐⭐⭐ Excellent
GPT-5-mini⚡⚡⚡ Very Fast€ Very Low⭐⭐⭐⭐ Excellent
GPT-4o⚡⚡ Fast€€ Medium⭐⭐⭐⭐⭐ Outstanding
Reasoning Models⚡ Moderate€€€ Higher⭐⭐⭐⭐⭐ Outstanding

Recommendation: Start with GPT-4o-mini or GPT-5-mini for optimal speed and cost efficiency

4. Optimize Product Data​

Best Practices:

  • Keep product descriptions concise
  • Reduce number of product variants
  • Optimize category structure
  • Minimize custom fields

Configuration Issues​

Issue: Checkboxes not visible in plugin configuration (Shopware 6.7)​

Cause: Plugin uses modern Shopware 6.7 type="bool" fields

Solution:

# Rebuild administration
bin/build-administration.sh

# Clear cache
bin/console cache:clear

Then refresh browser (Ctrl + F5)

Issue: Theme colors not applying​

Check:

  1. ✅ Standard (Anpassbar) theme selected?
    • Other themes have fixed colors
  2. ✅ Hex color format correct?
    • Must be format: #3b82f6 (include the #)
  3. ✅ Storefront compiled after change?

Solution:

# Rebuild storefront
bin/build-storefront.sh

# Clear cache
bin/console cache:clear

Hard refresh browser: Ctrl + F5

Issue: CMS element not available in editor​

Check:

  1. Plugin activated?
  2. Assets compiled?
  3. Browser cache cleared?

Solution:

# Refresh plugin list
bin/console plugin:refresh

# Verify activation
bin/console plugin:list | grep FelAIProductAdvisor

# Rebuild storefront
bin/build-storefront.sh

# Clear cache
bin/console cache:clear

Error: "API Key Invalid"​

Cause:

  • Invalid or expired OpenAI API key
  • API key not properly saved

Solution:

  1. Navigate to FEL OAI Assistants Manager plugin settings
  2. Re-enter your OpenAI API key
  3. Click "API Test" to verify
  4. Save configuration
  5. Clear cache: bin/console cache:clear

Error: "Rate Limit Exceeded"​

Cause:

  • Too many API requests in short time
  • OpenAI rate limits reached

Solution:

  • Wait a few minutes before trying again
  • Increase Wartezeit (Sekunden) in configuration
  • Upgrade OpenAI plan for higher rate limits
  • Reduce concurrent chatbot usage

Error: "Assistant Not Found"​

Cause:

  • Selected Assistant was deleted in OpenAI
  • Assistant ID mismatch

Solution:

  1. Navigate to base plugin: FEL OAI Assistants Manager
  2. Verify Assistant still exists
  3. Recreate Assistant if deleted
  4. Re-select Assistant in CMS element configuration

Debugging​

Enable Shopware Debug Mode​

For detailed error information:

In .env.local:

APP_ENV=dev

Then:

bin/console cache:clear
Production

Never leave debug mode enabled on production systems!

Check Shopware Logs​

Monitor logs for errors:

# Real-time log monitoring
tail -f var/log/prod-*.log

# Search for specific errors
grep -i "error" var/log/prod-*.log

# Check recent entries
tail -n 100 var/log/prod-*.log

Browser Console Debugging​

Enable browser developer tools:

  1. Press F12 (or Cmd + Option + I on Mac)
  2. Go to Console tab
  3. Look for red error messages
  4. Go to Network tab to check API requests

Common Console Errors:

ErrorCauseSolution
404 Not FoundAssets not compiledRebuild storefront
Uncaught TypeErrorJavaScript conflictCheck other plugins
Network ErrorAPI unreachableCheck firewall/connectivity
CORS ErrorCross-origin issueVerify API configuration

Common Questions & Solutions​

Q: Chat history disappears on page reload​

A: Chat history is stored in browser's LocalStorage. This is intentional for privacy.

Options:

  • Chat persists during same session
  • Closes when browser/tab closes
  • No server-side storage by design

Q: Chatbot shows products from wrong category​

A: Check category restriction settings:

  1. Edit CMS element
  2. Verify "Kategorie" field
  3. Ensure correct category selected
  4. Check "Kategorien ausschließen" in global settings

Q: Product images not displaying in chat​

A: Possible causes:

  1. Image URL issues

    • Check product has media assigned
    • Verify media URLs are accessible
    • Check file permissions

  2. Thumbnail generation

    # Regenerate thumbnails
    bin/console media:generate-thumbnails

Q: Multiple chatbots on one page conflict​

A: This should work normally, but to avoid issues:

  • Use different Assistants for each instance
  • Ensure unique Berater Titel for each
  • Test thoroughly before deploying

Performance Optimization Checklist​

Use this checklist to diagnose performance issues:

  • ✅ Using GPT-4o-mini or GPT-5-mini (fastest, most cost-effective models)
  • ✅ Excluded unnecessary categories
  • ✅ Limited property groups (< 10)
  • ✅ Max description length set to 300-500
  • ✅ Search result limit: 6-8 products
  • ✅ Display limit: 4 products in chat
  • ✅ Wartezeit set to 1-2 seconds
  • ✅ Max. Versuche set to 30-40
  • ✅ Product descriptions are concise
  • ✅ Server has adequate resources (2GB+ RAM)

Getting Help​

Before Contacting Support​

Gather this information:

  1. System Information:

    • Shopware version: bin/console --version
    • PHP version: php -v
    • Plugin version: Check in plugin manager

  2. Error Details:

    • Exact error message
    • When error occurs
    • Steps to reproduce
    • Browser console screenshot

  3. Log Files:

    • Recent entries from var/log/prod-*.log
    • JavaScript console errors
    • Network tab errors (F12)

Contact Support​

Email:info@5-elements-design.de

Include in your message:

  • System information (above)
  • Detailed error description
  • Screenshots of errors
  • Steps to reproduce
  • What you've already tried

Response Time:

  • Standard: 24-48 hours
  • Urgent: Mark email subject with [URGENT]

Additional Resources​

FAQ: Frequently Asked Questions​

Q: Does the plugin cost money to use? A: The plugin itself may have a license cost, but you also need an OpenAI API account with credits. Costs are per API request. With mini models (GPT-4o-mini, GPT-5-mini), API costs are very affordable. Premium models require monitoring token usage.

Q: How many Assistants can I create? A: Unlimited - create different Assistants for different categories or languages.

Q: Can I have multiple chatbots on one page? A: Yes, you can add multiple CMS elements with different Assistant configurations.

Q: Does it support multiple languages? A: Yes, the chatbot automatically adapts to the customer's language. Create separate Assistants per language for best results.

Q: Are chat conversations saved? A: Locally in the customer's browser (LocalStorage) only. No server-side persistent storage for privacy reasons.

Q: What happens if OpenAI is down? A: The chatbot won't function during outages. Check https://status.openai.com for status updates.

Still Need Help?

If you couldn't find a solution here, don't hesitate to contact our support team at support@5elements.de. We're here to help!