Skip to main content

Troubleshooting Guide

This guide helps you resolve common issues with the NextGen OpenAI Chatbot plugin.

Quick Diagnostics​

Is the Chatbot Working?​

✅ Basic Functionality Check:

  1. Can you see the chat icon on your storefront?
  2. Does the chat window open when clicked?
  3. Does the chatbot respond to "Hello"?
  4. Are responses relevant and helpful?

❌ If any step fails, continue to the relevant section below.

Installation Issues​

Plugin Not Visible​

Symptoms:

  • Chat icon doesn't appear on storefront
  • Plugin shows as installed but not working
  • No response when trying to access chat

Solutions:

  1. Check Plugin Status:

    bin/console plugin:list

    Ensure FelOaiChatbot shows as "Active"

  2. Activate Plugin:

    bin/console plugin:activate FelOaiChatbot

  3. Clear Cache:

    bin/console cache:clear
    bin/console cache:warmup

  4. Rebuild Assets:

    bin/console assets:install

Dependency Issues​

Symptoms:

  • Installation fails with dependency errors
  • Plugin conflicts with other extensions
  • Missing required packages

Solutions:

  1. Check Dependencies:

    composer show fel/o-a-i-assistants-manager

  2. Install Dependencies:

    composer install

  3. Update Dependencies:

    composer update

  4. Resolve Conflicts:

    • Check for plugin conflicts
    • Update Shopware to latest version
    • Review system requirements

Configuration Issues​

API Connection Problems​

Symptoms:

  • "API connection failed" errors
  • Chatbot not responding
  • Authentication errors

Solutions:

  1. Verify API Key:

    • Check if API key starts with sk-
    • Ensure no extra spaces or characters
    • Test with a fresh API key

  2. Check OpenAI Account:

    • Verify billing is enabled
    • Ensure sufficient credits
    • Check API usage limits

  3. Test API Connection:

    • Use the built-in "Test API Key" button
    • Check OpenAI Platform status
    • Verify network connectivity

Common API Key Issues:

❌ sk-abc123... (truncated key)
✅ sk-proj-abc123def456... (full key)

❌ API key with spaces
✅ API key without spaces

❌ Expired or revoked key
✅ Active, valid key

Assistant Configuration Problems​

Symptoms:

  • "Assistant not found" errors
  • Responses don't match your configuration
  • Assistant behaves unexpectedly

Solutions:

  1. Verify Assistant ID:

    • Check format starts with asst_
    • Ensure Assistant exists in OpenAI Platform
    • Verify Assistant is not deleted

  2. Check Assistant Configuration:

    • Review Assistant instructions
    • Verify enabled functions
    • Check model selection

  3. Test Assistant Directly:

    • Use OpenAI Playground to test
    • Verify Assistant works independently
    • Check for recent changes

Permission Issues​

Symptoms:

  • "Access denied" errors
  • Chatbot not visible to customers
  • Authentication problems

Solutions:

  1. Check Plugin Settings:

    • Verify "Enable Plugin" is checked
    • Review authentication settings
    • Check customer group restrictions

  2. Customer Group Configuration:

    • Verify customer groups exist
    • Check if customer is in allowed groups
    • Test with different customer accounts

  3. Clear Customer Sessions:

    bin/console cache:pool:clear cache.app

Functional Issues​

Chatbot Not Responding​

Symptoms:

  • Chat window opens but no responses
  • "Thinking" indicator stays forever
  • Error messages in chat

Diagnostic Steps:

  1. Check Browser Console:

    • Open Developer Tools (F12)
    • Look for JavaScript errors
    • Check Network tab for failed requests

  2. Test in Different Browser:

    • Try incognito/private mode
    • Test with different browsers
    • Check mobile devices

  3. Verify Server Logs:

    tail -f var/log/prod.log

Common Solutions:

  1. Clear Browser Cache:

    • Force refresh (Ctrl+F5)
    • Clear cookies and cache
    • Disable browser extensions

  2. Check Network Issues:

    • Verify internet connectivity
    • Check firewall settings
    • Test API access directly

  3. Server Configuration:

    • Verify PHP settings
    • Check memory limits
    • Review timeout settings

Poor Response Quality​

Symptoms:

  • Irrelevant responses
  • Incorrect product suggestions
  • Outdated information

Solutions:

  1. Review Assistant Instructions:

    • Update with current information
    • Add specific guidelines
    • Include example responses

  2. Update Knowledge Base:

    • Refresh FAQ content
    • Update meta information
    • Review product data

  3. Optimize Configuration:

    • Adjust search limits
    • Review category filters
    • Update property settings

Search Not Working​

Symptoms:

  • "No products found" errors
  • Irrelevant search results
  • Search functionality not available

Solutions:

  1. Check Product Data:

    • Verify products are active
    • Check product descriptions
    • Review category assignments

  2. Configuration Review:

    • Check search result limits
    • Review category blacklists
    • Verify property settings

  3. Test Search Manually:

    • Use Shopware's built-in search
    • Check product visibility
    • Verify search index

Performance Issues​

Slow Response Times​

Symptoms:

  • Long delays before responses
  • Timeout errors
  • Poor user experience

Solutions:

  1. Optimize Configuration:

    • Reduce search result limits
    • Limit product description length
    • Use property whitelists

  2. Check API Usage:

    • Monitor OpenAI usage dashboard
    • Check for rate limits
    • Optimize token usage

  3. Server Performance:

    • Check server resources
    • Optimize database queries
    • Review caching settings

High API Costs​

Symptoms:

  • Unexpected billing charges
  • Rapid credit consumption
  • Budget alerts from OpenAI

Solutions:

  1. Analyze Usage:

    • Review OpenAI usage dashboard
    • Check token consumption patterns
    • Identify expensive operations

  2. Optimize Settings:

    • Reduce input length limits
    • Limit search results
    • Optimize product descriptions

  3. Implement Limits:

    • Set customer group restrictions
    • Add rate limiting
    • Monitor usage regularly

Browser Compatibility​

JavaScript Errors​

Symptoms:

  • Console errors
  • Broken functionality
  • Layout issues

Solutions:

  1. Check Browser Support:

    • Verify modern browser usage
    • Check JavaScript enabled
    • Review browser extensions

  2. Update Resources:

    • Clear browser cache
    • Update plugin assets
    • Check for conflicts

  3. Test Compatibility:

    • Test in multiple browsers
    • Check mobile devices
    • Verify responsive design

Mobile Issues​

Symptoms:

  • Poor mobile experience
  • Touch interaction problems
  • Layout breaking

Solutions:

  1. Responsive Design:

    • Check viewport settings
    • Verify touch targets
    • Test on different devices

  2. Performance Optimization:

    • Optimize for mobile networks
    • Reduce resource usage
    • Implement progressive loading

Data and Privacy​

GDPR Compliance Issues​

Symptoms:

  • Cookie consent problems
  • Data handling concerns
  • Privacy policy conflicts

Solutions:

  1. Review Privacy Settings:

    • Check cookie configuration
    • Verify consent mechanisms
    • Update privacy policies

  2. Data Handling:

    • Review data collection
    • Check retention policies
    • Implement deletion procedures

  3. Compliance Verification:

    • Audit data flows
    • Review legal requirements
    • Consult with legal team

Local Storage Problems​

Symptoms:

  • Chat history not saving
  • Settings not persisting
  • Storage quota exceeded

Solutions:

  1. Browser Storage:

    • Check storage permissions
    • Clear existing data
    • Verify quota limits

  2. Configuration Review:

    • Check storage settings
    • Verify consent handling
    • Test different browsers

Advanced Diagnostics​

Debug Mode​

Enable Debug Logging:

# In your .env file
APP_DEBUG=true
APP_ENV=dev

Check Logs:

tail -f var/log/dev.log | grep -i "fel.*chatbot"

Network Analysis​

Check API Requests:

  1. Open Browser DevTools
  2. Go to Network tab
  3. Look for requests to /fel/chat/
  4. Check response status and content

Database Queries​

Check Configuration:

SELECT * FROM system_config WHERE configuration_key LIKE 'FelOaiChatbot%';

Getting Help​

Before Contacting Support​

Gather Information:

  • Plugin version
  • Shopware version
  • PHP version
  • Error messages
  • Browser information
  • Steps to reproduce

Contact Information​

Support Channels:

Include in Support Request:

  • Detailed problem description
  • Error messages and screenshots
  • System information
  • Configuration details
  • Steps already attempted

Community Resources​

Additional Help:

  • Shopware Community Forum
  • OpenAI Platform Documentation
  • Stack Overflow (tag: shopware)
  • GitHub Issues (if applicable)

Still Having Issues? Don't hesitate to contact our support team. We're here to help you get the most out of your NextGen OpenAI Chatbot.