Skip to main content

Troubleshooting & Common Issues

Here you'll find solutions to the most common problems with the OpenAI Agents Manager plugin.

🔍 Diagnostic Checklist​

Before diving into specific issues, check these basics:

  • Plugin is installed and activated
  • OpenAI API key is configured
  • OpenAI account has sufficient credit
  • Agent is activated (Is Active = On)
  • Shopware cache has been cleared (bin/console cache:clear)

❌ Error Messages & Solutions​

"Missing OpenAI API Key"​

Problem: No API key configured or plugin cannot find it.

Solutions:

  1. Check API key:

    • Go to Settings → System → Plugins
    • Open the configuration of "OpenAI Agents Manager"
    • Check if the "API Key" field is filled in

  2. Re-enter key:

  3. Clear cache:

    bin/console cache:clear

"Invalid API Key" / "Authentication failed"​

Problem: The API key is invalid or has been revoked.

Possible causes:

  • Key was copied incorrectly (spaces at beginning/end)
  • Key was revoked in OpenAI
  • Key belongs to a different organization

Solutions:

  1. Copy key again:

    • Make sure to copy the complete key
    • Check for hidden spaces

  2. Create new key:

  3. Run test:

    • In plugin configuration click "Test API Key"

"Insufficient quota" / "You exceeded your current quota"​

Problem: Your OpenAI credit is exhausted.

Solution:

  1. Check credit:

  2. Add credit:

    • Click "Add payment method" (if not already done)
    • Add credit (e.g., 20 USD)

  3. Enable automatic recharge:

    • Enable under "Auto recharge"
    • Set threshold (e.g., 5 USD)
    • Set recharge amount (e.g., 20 USD)

"Rate limit exceeded"​

Problem: Too many API requests in a short time.

Causes:

  • Multiple users using the agent simultaneously
  • Agent calls too many tools in succession
  • OpenAI's limit for your account type has been reached

Solutions:

  1. Wait briefly:

    • Wait 1-2 minutes
    • Try again

  2. Increase rate limit (for paying customers):

  3. Reduce tools:

    • Deactivate unneeded tools
    • Optimize your instructions

"Agent not found" / "No agents found"​

Problem: System cannot find an agent or agent was deleted.

Solutions:

  1. Agent exists?

    • Go to 5E OAI Agent Manager
    • Check if your agent is in the list

  2. Agent activated?

    • Open the agent
    • Set "Is Active" to On
    • Save

  3. Set default agent:

    • If no specific agent is called
    • Set "Is Default" to On for one agent

"Thread creation failed"​

Problem: Conversation (thread) could not be created.

Solutions:

  1. API key valid?

    • Test the key in plugin configuration

  2. Credit available?

    • Check your OpenAI credit

  3. Clear cache:

    bin/console cache:clear

🤖 Agent Issues​

Agent doesn't respond / No response​

Checklist:

  1. ✅ Agent activated?

    • "Is Active" = On

  2. ✅ API key valid?

    • Test in plugin configuration

  3. ✅ OpenAI credit available?

    • Check in OpenAI dashboard

  4. ✅ Instructions present?

    • At least "System Instructions" should be filled in

  5. ✅ Model selected?

    • E.g., gpt-4o-mini

Debug:

  • Open browser console (F12)
  • Check for errors in console
  • Check "Network" tab for failed requests

Agent gives incorrect/inappropriate answers​

Causes & Solutions:

  1. Instructions too vague:

    • ❌ Bad: "Be helpful"
    • ✅ Good: "You are a product advisor. Ask questions about budget, size, and color."

  2. Tools missing:

    • Agent cannot find products without product_search
    • Agent cannot check orders without get_order_status

  3. Temperature too high:

    • Lower temperature from 1.5 to 0.7
    • Makes answers more consistent

  4. Model too weak:

    • gpt-4o-mini is good but sometimes too limited for complex tasks
    • Test gpt-4o for better results

Agent doesn't call tools​

Problem: Agent doesn't use tools even though they are activated.

Solutions:

  1. Mention in instructions:

    You have access to the following tools:
    - product_search: Use this to search for products
    - get_order_status: Use this for order status queries

  2. Include tool names in questions:

    Customer: "Show me red jackets"

    Instructions should contain:
    "When asked about products, ALWAYS use product_search"

  3. Increase Reasoning Effort:

    • From low to medium or high
    • Gives agent more time to "think"

Agent responses are too long/too short​

Solutions:

  1. Adjust Verbosity:

    • Higher = longer responses
    • Lower = shorter responses

  2. Define in instructions:

    Keep your responses concise and under 3 sentences.

    or

    Give detailed, comprehensive responses with examples.

  3. Limit Max Output Tokens:

    • Set a limit (e.g., 500 tokens)
    • Prevents overly long responses

💰 Cost Issues​

Costs are unexpectedly high​

Diagnosis:

  1. Check Usage Dashboard:

  2. Expensive models?

    • gpt-5 and gpt-4o are 10-30x more expensive than gpt-4o-mini
    • Switch to cheaper models

  3. Too many tools activated?

    • Each tool increases token count
    • Deactivate unneeded tools

  4. Instructions too long?

    • Shorten instructions to essentials
    • Token caching helps, but shorter = cheaper

Optimizations:

  • ✅ Use gpt-4o-mini instead of gpt-4o
  • ✅ Activate only needed tools
  • ✅ Use search_logs to avoid repetitions
  • ✅ Set budget limits in OpenAI

Cached tokens not being used​

Problem: You see no cost savings from caching.

Explanation:

  • Caching only works with identical prompts
  • First request is never cached (only from the second onwards)

Verification:

  • In OpenAI Usage Dashboard: Look for "Cached Input Tokens"
  • After multiple conversations you should see significant cache usage

🔧 Technical Issues​

Plugin cannot be installed​

Solutions:

  1. Check PHP version:

    php -v

    At least PHP 8.2 required!

  2. Check Shopware version:

    • At least Shopware 6.7.0 required

  3. Update Composer:

    composer update

  4. Plugin dependencies:

    • Check if all required plugins are installed

Backend chat doesn't load / shows nothing​

Solutions:

  1. Clear browser cache:

    • Ctrl+Shift+Delete (Chrome/Edge)
    • Delete cookies & cache

  2. Check JavaScript errors:

    • F12 → Console
    • Errors in red text?

  3. Recompile assets:

    bin/console cache:clear
    bin/build-administration.sh

Vector Store not found​

Problem: "Vector store not found" or files are not loaded.

Solutions:

  1. Vector Store exists in OpenAI?

  2. Vector Store ID correct?

    • In agent configuration: Check the Vector Store ID
    • Format: vs_abc123...

  3. Files uploaded?

    • Vector Store must contain files
    • Status must be "completed"

🌐 Browser-specific Issues​

Chat works in Chrome but not in Firefox/Safari​

Solution:

  • Clear browser cache
  • Temporarily disable ad blocker
  • Check browser console for errors (F12)

📱 Mobile Issues​

Chat interface is unusable on smartphone​

Note: The backend is optimized for desktop.

Recommendation:

  • Use a desktop browser for administration
  • Frontend integrations should be mobile-optimized

🔐 Security Issues​

API key has been compromised​

Immediate actions:

  1. Revoke key:

  2. Create new key:

    • Create a new key
    • Enter it in Shopware

  3. Set budget limit:

    • Protect yourself from abuse
    • Set a monthly limit

📊 Performance Issues​

Agent responds very slowly (> 30 seconds)​

Causes & Solutions:

  1. Reasoning Effort too high:

    • high can take 10-30 seconds
    • Lower to medium or low

  2. Too many tools:

    • More tools = longer decision time
    • Deactivate unneeded tools

  3. Large Vector Store:

    • Many/large files = slow search
    • Reduce the number of files

  4. OpenAI servers overloaded:

    • Slower at certain times
    • Try again later

🆘 Emergency Measures​

Nothing works anymore!​

Step-by-step reset:

  1. Deactivate and reactivate plugin:

    bin/console plugin:deactivate FelOAIAssistantsManager
    bin/console plugin:activate FelOAIAssistantsManager

  2. Completely reinstall:

    bin/console plugin:uninstall FelOAIAssistantsManager
    bin/console plugin:install FelOAIAssistantsManager --activate

  3. Clear cache:

    bin/console cache:clear

  4. Recompile assets:

    bin/build-administration.sh
    bin/build-storefront.sh
Caution

With plugin:uninstall data may be lost! Create a backup beforehand.

📞 Contact Support​

If all solutions don't help:

Collect before contacting:​

  • ✅ Shopware version
  • ✅ Plugin version
  • ✅ PHP version
  • ✅ Exact error message (screenshot)
  • ✅ Browser console logs (F12 → Console)
  • ✅ What have you already tried?

Contact:​

📋 Frequently Asked Questions (FAQ)​

Can I use multiple agents simultaneously?​

Yes! You can create and use unlimited agents in parallel.

Can I clone/duplicate an agent?​

Not currently directly in the UI. Workaround: Create a new agent and manually copy instructions and tool selection.

Are conversations automatically deleted?​

No. Threads remain until you manually delete them.

Can I export the logs?​

Not directly in the UI, but the data is in the Shopware database (table fel_assistant_chat_message).

Does the plugin work with Shopware 6.6?​

No, at least Shopware 6.7.0 is required.

Next Steps​

Problem solved? Great!

➡️ Best Practices - Tips for optimal agents

➡️ Cost Management - Keep costs under control

➡️ Back to Main Documentation