Troubleshooting

Solutions for the most common issues you might encounter.

The Widget Doesn't Appear

Check it's enabled

1. Go to AxiaChat AI → Bots.
2. Make sure "Show on all pages as a floating widget" is checked in the bot's General section.
3. Or verify you've placed the shortcode [aichat id="your-bot"] on the page.

Check exclusions

Some pages (admin, checkout) may be excluded. Check if the current page is in an exclusion list.

JavaScript conflicts

1. Open your browser console (F12 → Console tab)
2. Look for red error messages
3. Common cause: another plugin or theme conflicting with the chat JavaScript

Cache issues

• Clear your caching plugin's cache (WP Rocket, W3 Total Cache, etc.)
• Clear your browser cache
• Test in an incognito/private window

The Bot Doesn't Respond

Verify your API key

1. Go to AxiaChat AI → Settings.
2. Check that the API key for the bot's provider is entered.
3. Test the key on the provider's website to confirm it's valid.

Check usage limits

• Review if daily limits have been reached in AxiaChat AI → Bots → Conversation Limits
• Check your balance/credits on the AI provider's dashboard

Connection errors

• Verify your server can connect to external APIs
• Some shared hosting providers block outgoing connections
• Check if api.openai.com, api.anthropic.com, or generativelanguage.googleapis.com are reachable from your server

Responses Are Incorrect or Generic

Check the context

1. Verify the bot has a context assigned (in Bots → General or Training → Context)
2. If using embeddings, check that content has been indexed
3. Re-index if the content has changed

Improve instructions

• Be more specific about how the bot should respond
• Add examples in the instructions
• Enable the "Use the provided CONTEXT" guideline

Try a better model

Smaller models sometimes give generic answers. Try GPT-4o, Claude Sonnet, or Gemini Pro for more accurate responses.

Embedding / Indexing Errors

OpenAI API key required

Embeddings always use OpenAI (text-embedding-3-small), even if your bot uses a different provider for chat. Make sure you have a valid OpenAI API key in AxiaChat AI → Settings.

Connection to api.openai.com

Your server must be able to reach api.openai.com. Test with:

# SSH into your server and run:
curl -I https://api.openai.com

Content too long

The plugin automatically chunks long content (~1,000 words per chunk). If a specific page fails, check for unusual formatting or extremely long content.

Easy Config Wizard Doesn't Appear

• The wizard only appears once, on first activation
• If it was already completed, it won't show again
• Access it at AxiaChat AI → Easy Config if available
• Or delete the aichat_easy_config_completed option from your database to restart it

LiveChat Not Working

• Plan check: LiveChat requires the Professional plan
• Agent availability: At least one agent must be marked as available
• Add-on enabled: Check AxiaChat AI → Settings → Add-ons

Webhooks Failing

Verify the URL

• Check the webhook URL is accessible
• Test the URL with cURL or Postman

Check parameters

• Verify sent parameters match what the external service expects
• Check AxiaChat AI → Logs → Tools to see what was sent vs. received

Timeout

If the external service is slow, increase the webhook timeout. Also optimize the receiving service.

Performance Issues

Too many embeddings

Limit indexed content to what's truly relevant. Consider Pinecone for large knowledge bases.

Model too large

Use "mini" or "nano" models for faster responses. Reserve larger models for complex queries.

Hosting limitations

Some shared hosting plans have limited CPU/memory. Consider upgrading to a VPS or managed WordPress host if you experience timeouts.

Debug Mode

AxiaChat AI includes a built-in debug panel in the admin area — no need to edit code. Follow these steps to capture and share diagnostic logs:

1. Enable debug logging

1. Go to AxiaChat AI → Settings.
2. Click the Advanced tab.
3. In the Debug & System Logs card, check "Enable debug logging".
4. Save the settings.

2. Reproduce the problem

Now perform the action that triggers the issue: send a message to the chatbot, index content, or whatever causes the error. The plugin will record detailed diagnostic information while logging is active.

3. Download the logs

1. Return to AxiaChat AI → Settings → Advanced.
2. You can preview the logs directly in the page (View / Refresh buttons) or download them individually.
3. For the fastest support, click "Export Diagnostics ZIP" at the bottom of the card. This bundles both log files plus an environment report (PHP version, active plugins, bot config, etc.). No API keys or passwords are included.

4. Send to support

Email the downloaded ZIP file to the support team at axiachat.org along with a brief description of the issue. The more context you include, the faster we can help.

5. Disable logging when done

Once you've captured the logs, uncheck "Enable debug logging" and save. Keeping it off during normal operation avoids unnecessary disk usage.

Frontend debugging

For JavaScript-level issues, add ?aichat_debug=1 to any page URL:

https://yoursite.com/?aichat_debug=1

This outputs detailed information in the browser console (F12).

Bot preview mode

Test a specific bot without affecting live visitors:

https://yoursite.com/?aichat_preview=1&bot=your-bot-slug

Still Need Help?

If none of the above resolves your issue:

1. Gather info: WordPress version, PHP version, active theme, active plugins
2. Describe the problem in detail
3. Include screenshots if possible
4. Contact us at axiachat.org or via the WordPress.org support forum