Troubleshooting

If you encounter issues while using AI Product Tools, use this guide to find solutions for common problems. This page covers everything from connection errors to content quality issues.

Quick Diagnostic Checklist

Before diving into specific issues, please go through this quick checklist to ensure your environment is correctly configured:

Plugin Active: Is the AI Product Tools plugin activated in your WordPress Plugins menu?
WooCommerce Installed: Is WooCommerce installed and active? The plugin requires WooCommerce to function.
API Key Validated: Have you entered and validated your API key in the API Configuration settings?
WordPress Updated: Are you running a recent version of WordPress (5.0+)?
PHP Version: Is your server running PHP 7.4 or higher? You can check this in your hosting dashboard or via WordPress Site Health.

API and Connection Issues

Invalid API Key

Symptoms: You see an error message stating "Invalid API Key" or "Authentication Failed" when testing the connection or trying to generate content.

Cause: The AI provider (OpenAI, Google, etc.) has rejected the key. This could be due to a typo, an expired key, or using a key from the wrong provider.

Fix:

Go to the API Configuration page.
Verify the format of your key:
- OpenAI: Should start with sk-proj- or sk-.
- Gemini: Usually starts with AIza.
- OpenRouter: Starts with sk-or-v1-.
- Claude (Anthropic): Starts with sk-ant-.
Ensure there are no accidental spaces at the beginning or end of the key.
Log in to your provider's dashboard and create a new key if the current one is old or potentially compromised.
Click the Test Connection button to verify the new key.

Rate Limit Errors (429 Status)

Symptoms: Generation fails with a "429 Too Many Requests" error or a message about rate limits.

Cause: You have exceeded the number of requests allowed by your AI provider within a specific timeframe. This is common on free or lower-tier API plans.

Fix:

Wait for a few minutes. Most rate limits are calculated per minute or per hour.
If you are using OpenAI, check your "Tier" in their dashboard. Tier 1 and above have much higher limits than the Free tier.
In the plugin settings, increase the Generation Interval (if available) to slow down the request rate during bulk operations.
Consider switching to a different provider like OpenRouter or Gemini if you frequently hit limits with one provider.

Connection Timeout

Symptoms: The generation process spins indefinitely and eventually fails with a "Connection Timeout" or "Gateway Timeout" error.

Cause: Your server is unable to reach the AI provider's API servers within the allowed time. This is often caused by server-side firewalls, hosting restrictions, or very slow DNS resolution.

Fix:

Contact your hosting provider and ask them to whitelist the API endpoints for your chosen provider (e.g., api.openai.com, generativelanguage.googleapis.com).
Ensure that the PHP cURL extension is enabled and up to date on your server.
Check if your server has any outgoing request limits or security plugins (like Wordfence) that might be blocking the connection.

Model Not Available

Symptoms: You receive an error saying "Model not found" or "The requested model is not available."

Cause: The specific AI model you selected has been deprecated by the provider, or your API key does not have access to that specific model (e.g., trying to use GPT-4 with a key that only supports GPT-3.5).

Fix:

Go to API Configuration.
Click the Refresh Models button to fetch the latest list of available models for your key.
Select a different model from the dropdown menu and save settings.
Check the AI Models Guide for recommendations on which models to use.

Billing Not Set Up

Symptoms: API key is valid, but you get an error saying "Insufficient funds" or "Billing required."

Cause: Most AI providers require a valid payment method on file, even if you are using a "Free" tier or have credits. OpenAI, in particular, requires you to add a minimum balance to your account before the API will function.

Fix:

Log in to your AI provider's billing dashboard.
Ensure a credit card is linked and that you have a positive balance.
Check for any "Usage Limits" you might have set that are preventing further requests.

OpenAI often requires a minimum $5 deposit to activate API access for new accounts.

Content Generation Issues

Empty or Blank Content Generated

Symptoms: The generation process completes, but the resulting description or title is empty.

Cause: This usually happens if the product has no data (title, categories, attributes) for the AI to work with, or if the AI provider returned an error that wasn't properly displayed in the UI.

Fix:

Ensure the product has a clear title and is assigned to at least one category.
Check the Prompt Settings to ensure you haven't accidentally deleted the instructions.
Try generating for a different product to see if the issue is product-specific.
Check the browser console (F12) for any hidden error messages during the generation process.

Low Quality or Generic Content

Symptoms: The AI generates content, but it is too short, repetitive, or doesn't accurately describe the product.

Cause: The AI doesn't have enough context about your product, or the prompt instructions are too vague.

Fix:

Add more details to your WooCommerce product: attributes (color, material, size), tags, and a short description.
Use Custom Variables to feed specific data points into the AI.
Switch to a more capable model like GPT-4o or Claude 3.5 Sonnet.
Refine your prompts in Prompt Settings. Be specific about the tone and structure you want.

Wrong Language Output

Symptoms: The AI generates content in English when your store is in another language, or vice versa.

Cause: The output language is not correctly set in the plugin settings.

Fix:

Go to Content Settings.
Find the Output Language setting and ensure it matches your desired language.
If you are using "Auto-detect," try setting the language explicitly to your store's primary language.

Generation Stuck at "Generating..."

Symptoms: The loading spinner stays on the screen for more than 60 seconds without any progress.

Cause: A JavaScript error in the browser, a server-side crash, or an aggressive caching plugin interfering with the REST API request.

Fix:

Wait at least 60 seconds; high-quality models can sometimes take a while to respond.
Refresh the page and try again.
Open the browser console (Right-click > Inspect > Console) and look for red error messages.
Temporarily disable any caching or optimization plugins (like WP Rocket or Autoptimize) to see if they are the cause.

Content Not Saving to Products

Symptoms: You approve the generated content, but it doesn't appear on the product page.

Cause: Database permission issues, conflicts with other product-related plugins, or a failure in the "Apply" process.

Fix:

Ensure your WordPress user has the edit_products capability.
Check if you have any "Revision" or "Workflow" plugins that might be intercepting product updates.
Clear your site's cache (server-side and plugin-side) after applying the changes.
Verify that the content appears in the "Draft Contents" section if you are using an automation job.

HTML Tags Showing as Text

Symptoms: You see tags like <div> or <strong> visible on your product page instead of formatted text.

Cause: Your WordPress theme or a security plugin is "escaping" the HTML, treating it as plain text for safety.

Fix:

Check your theme settings to see if it supports HTML in product descriptions.
If you are using a security plugin, check for settings related to "HTML filtering" or "XSS protection."
In the plugin's Content Settings, try switching between "HTML" and "Plain Text" output modes.

Duplicate Content for Similar Products

Symptoms: Multiple products get almost identical descriptions.

Cause: The products have very similar titles and attributes, leading the AI to the same conclusion.

Fix:

Add unique attributes to each product (e.g., SKU, specific dimensions, unique features).
Use the "Advanced" generator which allows for more variety in output.
Adjust the "Temperature" setting in API Configuration to a higher value (e.g., 0.8) to encourage more creative and varied responses.

Bulk Operation Issues

Batch Stops Midway

Symptoms: A bulk generation task for 100 products stops after 20 products.

Cause: Server execution time limits, rate limits from the AI provider, or your browser tab being closed/put to sleep.

Fix:

Keep the browser tab active and in the foreground while bulk operations are running.
Check the Job Logs to see if a specific error caused the stop.
Ensure you have enough credits available for the entire batch.
If it's a server timeout, try processing smaller batches (e.g., 20 products at a time).

Progress Bar Not Moving

Symptoms: The bulk operation is active, but the progress bar hasn't moved in several minutes.

Cause: The system might be waiting out a rate limit "cool down" period, or a specific product is taking a very long time to process.

Fix:

Check the "Status" message next to the progress bar. It often indicates if the system is "Waiting" or "Retrying."
Check your AI provider's dashboard for any active rate limit warnings.
Refresh the page; the plugin is designed to resume bulk operations from where they left off.

Some Products Skipped

Symptoms: The bulk operation finishes, but several products are marked as "Skipped" or "Failed."

Cause: These products likely lacked a title, were already processed (if "Skip existing" was enabled), or encountered a specific API error.

Fix:

Review the results table at the end of the bulk run.
Click on the "Error" icon for any failed product to see the specific reason.
Ensure all products have the minimum required data before starting a bulk run.

Content Not Appearing After Approval

Symptoms: You approved a batch of descriptions in the history table, but they aren't on the products.

Cause: The "Apply" process is still running in the background, or a cache is preventing you from seeing the updates.

Fix:

Wait a few minutes for the background process to complete.
Clear your browser cache and any WordPress caching plugins.
Check the product in the WordPress admin to see if the description is present there.

Credit System Issues

"Insufficient Credits" Error

Symptoms: The plugin says you have 0 credits, but you know you have a balance.

Cause: Your local credit cache is outdated, or your site is not correctly registered with the licensing server.

Fix:

Go to the Credits and Plans page.
Click the Refresh Balance or Troubleshoot button.
Ensure your license is active in the Freemius account dashboard.
Check if you have multiple sites and if the credits are assigned to the correct one.

Balance Not Updating

Symptoms: You used credits, but the balance shown in the dashboard hasn't changed.

Cause: The credit balance is cached for 5 minutes to improve performance.

Fix:

Wait 5 minutes and refresh the page.
Use the manual refresh button in the credit panel.
Check the "Usage History" to see if the credits were actually deducted.

Terms Not Accepted / Registration Required

Symptoms: You cannot use any features, and a message asks you to accept terms or register.

Cause: First-time setup requires you to connect your site to the AI Product Tools network.

Fix:

Follow the prompts in the admin notice to accept the terms of service.
Ensure you have completed the Quick Start onboarding.

Metabox Issues

AI Product Tools Metabox Missing

Symptoms: You don't see the AI generation options on the WooCommerce product edit page.

Cause: The metabox is hidden in "Screen Options," the user role doesn't have permission, or WooCommerce is not active.

Fix:

On the product edit page, click Screen Options at the top right.
Ensure "AI Product Tools" is checked.
Verify that the plugin is active and that you are logged in as an Administrator or Store Manager.
Check if another plugin is causing a JavaScript error that prevents the metabox from rendering.

Automation Issues

Jobs Stuck at "Scheduled"

Symptoms: An automation job is set to run, but it never moves to the "Running" state.

Cause: WordPress "Cron" (the scheduling system) is not being triggered. WP-Cron only runs when someone visits your website.

Fix:

Visit your website yourself to trigger the cron system.
If your site has low traffic, set up a "Real System Cron" in your hosting control panel (cPanel/Plesk) to call wp-cron.php every 5 minutes.
Check if DISABLE_WP_CRON is set to true in your wp-config.php file.

Job Timeout / Stuck in "Running"

Symptoms: A job has been "Running" for hours but hasn't processed any products.

Cause: The job encountered a fatal error or hit a server timeout. The system has a 30-minute safety window before it considers a job "stuck."

Fix:

Wait at least 30 minutes; the system will automatically attempt to recover stuck jobs.
Reduce the "Batch Size" in the job settings to make each step faster.
Check the Job Logs for "Fatal Error" messages.

Jobs Running but No Drafts

Symptoms: The job completes, but the "Draft Contents" table is empty.

Cause: You might have "Auto-apply" enabled, which skips the draft stage and saves directly to products. Or, the filters you set for the job didn't match any products.

Fix:

Check the job settings to see if "Auto-apply" is turned on.
Verify your product filters (categories, status, etc.) to ensure they actually target products that need generation.
Check the logs to see if products were skipped because they already had descriptions.

Chatbot Issues

Chatbot Not Appearing

Symptoms: The chat widget is not visible on your website's frontend.

Cause: The chatbot is disabled in settings, or there is a conflict with your theme's CSS/JS.

Fix:

Go to AI Shop Assistant settings and ensure it is toggled to Enabled.
Check the "Display Settings" to see if you have restricted it to certain pages.
Clear your site's cache and your browser cache.
Check the browser console for any errors related to aipt-chatbot.js.

Bot Says "I don't know"

Symptoms: The chatbot answers general questions but can't find any products from your store.

Cause: The Store Index has not been built or is outdated.

Fix:

Go to the Store Index page.
Click Build Index and wait for it to complete.
Ensure you have added "Store Context" in the chatbot settings to give the AI a general idea of what you sell.

Slow Responses

Symptoms: The chatbot takes 10+ seconds to reply to every message.

Cause: Using a slow AI model or trying to search through too many products at once.

Fix:

Switch to a "Flash" or "Turbo" model (e.g., Gemini 1.5 Flash or GPT-4o-mini).
Reduce the Max Products per Query setting in the chatbot configuration.
Ensure your server's response time is healthy.

Store Index Issues

Build Fails

Symptoms: The indexing process stops with an error or simply disappears.

Cause: Server memory limits or execution time limits being reached during the indexing of a large catalog.

Fix:

Reduce the Batch Size in the Store Index settings.
Ensure your server has at least 512MB of PHP memory allocated.
Check the Action Scheduler logs (WooCommerce > Status > Scheduled Actions) for any failed aipt_index_batch tasks.

Build is Very Slow

Symptoms: Indexing 1,000 products takes several hours.

Cause: Low server resources or a very high "Delay between batches" setting.

Fix:

Check if your server is under heavy load from other tasks.
Use Index Profiles to only index the most important categories instead of your entire catalog.

Products Missing from Chat

Symptoms: The chatbot can find some products but not others.

Cause: The missing products were added after the last index build, or they don't match the filters in your Index Profile.

Fix:

Run an incremental index update or a full rebuild.
Check your Store Index profiles to ensure no categories are accidentally excluded.

SEO Meta Issues

No SEO Plugin Detected

Symptoms: You see a warning that no supported SEO plugin is found.

Cause: You don't have Yoast SEO, Rank Math, or All in One SEO installed and active.

Fix:

Install one of the supported SEO plugins.
Ensure the plugin is activated.
Refresh the SEO Meta Generator page.

Generate Button Disabled

Symptoms: The "Generate" button in the SEO section cannot be clicked.

Cause: No SEO plugin is active, or you haven't selected any products to process.

Fix:

Select at least one product from the list.
Verify that an SEO plugin is detected in the status bar at the top of the page.

Performance Issues

Admin Dashboard Slow

Symptoms: Navigating the AI Product Tools menus feels sluggish.

Cause: Large amounts of history data in the database or conflicts with other heavy admin plugins.

Fix:

Go to settings and use the "Clear History" tool to prune old generation records.
Ensure you are using a high-quality hosting provider; AI processing can be resource-intensive.
Disable any unnecessary admin-side plugins.

Generation Takes 30+ Seconds

Symptoms: Even for a single product, the AI takes a long time to respond.

Cause: Complex prompts, slow AI models, or provider-side latency.

Fix:

Simplify your prompts in Prompt Settings.
Switch to a faster model like GPT-4o-mini.
Check the status page of your AI provider (e.g., status.openai.com) for any ongoing incidents.

General Issues

Settings Not Saving

Symptoms: You change a setting, click save, but it reverts to the old value.

Cause: Security plugins (like ModSecurity) blocking the save request, or database write permissions.

Fix:

Check if your hosting has "ModSecurity" enabled and ask them to check the logs for blocked requests to wp-json/aipt/v1/settings.
Try saving settings from a different browser or in Incognito mode.

Credits Not Syncing

Symptoms: Your credit balance is stuck and won't update even after a refresh.

Cause: A communication breakdown between your server and the licensing server.

Fix:

Use the Troubleshoot button in the credit panel.
Ensure your server can make outgoing HTTPS requests to freemius.com and the plugin's API server.

Premium Features Not Working

Symptoms: You paid for Pro, but features like Automation or Chatbot are still locked.

Cause: You are still running the "Free" version of the plugin.

Fix:

Log in to your Freemius account.
Download the Premium version of the plugin.
Deactivate and delete the Free version from your site (your settings will be saved).
Upload and activate the Premium version.
Enter your license key when prompted.

Still Need Help?

If you've gone through this guide and are still experiencing issues, we are here to help!

Support Ticket: Open a ticket through our Support Page.
Documentation: Re-read the Quick Start guide to ensure no steps were missed.
Community: Check our forums for similar issues reported by other users.

When contacting support, please include:

Your WordPress and PHP versions.
The AI provider and model you are using.
Any specific error messages you see in the logs or browser console.

What's Next?

Now that you've resolved your issues, check out these resources to get the most out of the plugin:

Troubleshooting

On this page