Troubleshooting Guide

Time to complete: 5-10 minutes per issue You'll learn: How to identify and fix the most common AI Product Tools issues

This guide helps you solve problems fast. Jump directly to your issue using the quick links below.

---

Quick Diagnostic Checklist

Before diving into specific issues, run this quick check:

• Plugin active? Check Plugins page
• WooCommerce installed? Required for AI Product Tools
• API key validated? Settings → API Provider Configuration
• WordPress updated? Requires WordPress >= 5.0.0
• PHP version? Requires PHP >= 7.4

Most issues (80%+) are resolved by:

1. Re-validating your API key
2. Checking WooCommerce is active
3. Clearing WordPress cache

---

Quick Links to Common Issues

• API Key Problems
• Generation Failures
• Credit System Issues
• Metabox Not Showing
• Automation Not Running
• Slow Performance
• Empty Content Generated

---

API Key Problems

Issue: "Invalid API key" error

Symptoms:

• Red error message when validating key in Settings
• Error appears immediately after clicking "Validate"
• All generation attempts fail with authentication errors

Cause:

• Incorrect API key (typo or wrong key copied)
• API key revoked or expired at provider
• Extra spaces before/after key when pasting

Fix:

1. Go to your AI provider dashboard:

   • OpenAI: https://platform.openai.com/api-keys
   • Gemini: https://ai.google.dev
   • OpenRouter: https://openrouter.ai/keys

2. Generate a NEW API key (don't reuse old one)

3. Copy the entire key (no spaces, no line breaks)

4. In AI Product Tools:

   • Navigate to Settings → API Provider Configuration
   • Delete the old key completely
   • Paste new key (Ctrl+V or Cmd+V)
   • Important: Don't type manually - paste only

5. Click "Validate API Key"

6. Success indicator: Green checkmark appears + "Connected" status

---

Issue: Rate limit errors (429 status code)

Symptoms:

• Error message: "Rate limit exceeded" or "Too many requests"
• Generations work, then suddenly stop
• Status code 429 in error logs

Cause:

• Too many API requests in short time
• Free tier limits reached (OpenAI, Gemini)
• OpenRouter rate limits (varies by model)

Fix:

1. Check your provider's rate limits:

   • OpenAI: 3 requests/minute (free tier)
   • Gemini: 60 requests/minute (free tier)
   • OpenRouter: Varies by model

2. Reduce request frequency:

   • Use smaller batches in bulk generation (10 products instead of 100)
   • Add delays between automation job runs
   • Spread out generation throughout the day

3. Upgrade provider plan (if hitting limits frequently)

4. Wait 60 seconds then try again

---

Issue: API connection timeout

Symptoms:

• "Connection timed out" error
• Generation spins for 30+ seconds then fails
• Works sometimes, fails other times

Cause:

• Provider experiencing high load
• Your hosting server blocking outbound connections
• Firewall blocking connections

Fix:

1. Check provider status:

   • OpenAI: https://status.openai.com
   • Google Cloud: https://status.cloud.google.com
   • OpenRouter: https://openrouter.ai/status

2. Test from different network:

   • Try from your phone (mobile data)
   • If it works: contact your host about HTTPS restrictions

3. Contact hosting support:

   • Ask: "Can my site make HTTPS requests to api.openai.com?"
   • Request: "Please whitelist AI provider APIs"

4. Try different AI provider as temporary workaround

Code reference: src/Core/ErrorHandler.php

---

Generation Failures

Issue: Empty or blank content generated

Symptoms:

• Generation completes but shows empty field
• "Content generated successfully" message but nothing appears
• Preview shows blank text

Cause:

• Product missing required data (title, categories)
• API returned error but wasn't displayed
• Content filtered out by WordPress sanitization

Fix:

1. Check product has minimum data:

   • Product title (required)
   • At least one category (strongly recommended)
   • Short description or attributes (helps quality)

2. Test with simple product:

   • Create test product with title "Test Product"
   • Add to "Uncategorized" category
   • Generate description
   • If this works: original product had data issues

3. Check browser console for errors:

   • Press F12 in browser
   • Click "Console" tab
   • Look for red error messages
   • Share these with support if needed

4. Re-validate API key (Settings → API Provider Configuration)

---

Issue: Generated content is low quality or irrelevant

Symptoms:

• Content generated but doesn't match product
• Generic descriptions with wrong details
• Content repeats same phrases

Cause:

• Insufficient product data for AI to work with
• Default prompts not optimized for your products
• Wrong AI model selected for your needs

Fix:

1. Improve product data quality:

   • Add detailed product attributes (size, color, material)
   • Write clear, specific product titles
   • Add products to specific categories (not just "Uncategorized")
   • Include short descriptions or key features

2. Customize prompts for your niche:

   • Go to Settings → Prompt Templates
   • Add industry-specific instructions
   • Example: "Focus on organic materials and sustainability"
   • See Variables & Custom Fields for advanced templates

3. Try different AI model:

   • Settings → Model Selection
   • GPT-4o (OpenAI) for highest quality
   • Gemini Pro for multilingual
   • See AI Models for comparison

4. Use custom variables to include product specs automatically

Related: Best Practices for Content Quality

---

Issue: Generation stuck at "Generating..."

Symptoms:

• Progress indicator spins indefinitely
• No error message appears
• Page doesn't freeze, but nothing happens

Cause:

• API request succeeded but response not received
• JavaScript error preventing response handling
• Server response blocked by caching plugin

Fix:

1. Wait 60 seconds (some models are slow)

2. Check browser console (F12 → Console tab)

   • Look for red JavaScript errors
   • Look for network errors in Network tab

3. Disable caching temporarily:

   • If using WP Rocket, W3 Total Cache, etc.
   • Disable caching for admin pages
   • Try generation again

4. Clear browser cache:

   • Ctrl+Shift+Delete (Windows/Linux)
   • Cmd+Shift+Delete (Mac)
   • Select "Cached images and files"
   • Click "Clear data"

5. Try different browser (Chrome, Firefox, Edge)

---

Credit System Issues

Issue: "Insufficient credits" but plan shows credits available

Symptoms:

• Error: "Insufficient credits for this action"
• Freemius account shows remaining credits
• Balance not syncing with plugin

Cause:

• Credit balance cache outdated (5-minute cache)
• Site not registered with Ctrl API
• Background sync failed

Fix:

1. Force refresh balance:

   • Settings → Credits & Usage
   • Click "Force Refresh Balance"
   • Wait 5 seconds for sync

2. Check site registration:

   • Settings → Credits & Usage
   • Look for "Registration Required" message
   • If shown: Click "Register Site"

3. Clear credit cache:

   # Via WP-CLI (if available)
   wp transient delete aipt_ctrl_balance
   wp transient delete aipt_ctrl_costs

4. Wait 5 minutes for automatic sync, then try again

---

Issue: Balance not updating after use

Symptoms:

• Generate content successfully
• Credit balance number doesn't decrease
• Usage summary not showing new entries

Cause:

• Viewing cached balance (refresh needed)
• API sync delay (up to 5 minutes)
• Background sync disabled

Fix:

1. Refresh the page (F5)

2. Wait 5 minutes for cache expiry

3. Check usage summary:

   • Settings → Credits & Usage → View Usage Summary
   • Verify recent generations listed
   • If missing: balance deduction may have failed

4. Force refresh balance (Settings → Credits & Usage)

Expected behavior: Balance updates within 5 minutes of generation

---

Issue: Terms not accepted / Registration required

Symptoms:

• Error: "You must accept terms to continue"
• Error: "Site registration required"
• Can't use credit-based features

Cause:

• First-time setup not completed
• Terms of Service not yet accepted
• Site token not generated

Fix:

1. Accept Terms of Service:

   • Settings → Credits & Usage
   • Read Terms of Service
   • Click "Accept Terms"
   • Confirmation appears

2. Complete site registration:

   • Automatic after accepting terms
   • Manual: Click "Register Site" button
   • Wait for "Registration successful" message

3. Verify registration status:

   • Settings → Credits & Usage
   • Check for "Site Token" indicator
   • Status should show "Registered"

One-time setup: These steps only need to be completed once per site.

---

Metabox Not Showing

Issue: "AI Product Tools" metabox missing from product edit page

Symptoms:

• Edit product screen doesn't show AI Product Tools box
• Other metaboxes visible but not AI Product Tools
• Plugin is activated

Cause:

• Metabox hidden via Screen Options
• User role doesn't have required capability
• WooCommerce not active

Fix:

1. Check Screen Options:

   • Click "Screen Options" tab (top right of product edit page)
   • Look for "AI Product Tools" checkbox
   • If unchecked: Check the box
   • Metabox should appear immediately

2. Verify WooCommerce active:

   • Plugins → Installed Plugins
   • WooCommerce should show "Active" status
   • If not active: Click "Activate"

3. Check user capabilities:

   • User must be Administrator or Shop Manager
   • Requires edit_products capability
   • Regular users (Subscriber, Customer) can't see metabox

4. Refresh product edit page:

   • Save product
   • Close and reopen product edit screen

Code reference: src/Core/Init.php:356-372 (metabox registration)

---

Automation Not Running

Issue: Automation jobs stuck at "Scheduled" status

Symptoms:

• Created automation job shows "Scheduled"
• Next run time passes but job doesn't execute
• Job progress stays at 0%

Cause:

• WordPress Cron (WP-Cron) disabled
• Hosting environment blocks WP-Cron
• No site traffic to trigger cron (low-traffic sites)

Fix:

1. Check WP-Cron status:

   • Settings → System Status
   • Look for "WP-Cron Status" indicator
   • Should show "Enabled" ✓

2. Verify cron not disabled in wp-config.php:

   // Bad - this disables WP-Cron
   define('DISABLE_WP_CRON', true);
   
   // Good - WP-Cron enabled
   // (remove or comment out DISABLE_WP_CRON line)

3. Test cron manually:

   • Visit: yoursite.com/wp-cron.php in browser
   • Should see blank page (this is normal)
   • Check if job progressed (refresh Automation Jobs page)

4. Set up system cron (for high-performance sites):

   # Add to server crontab
   */5 * * * * cd /path/to/wordpress && wp cron event run --due-now

5. Alternative: Use free cron service:

   • Visit https://cron-job.org (free service)
   • Add job to ping yoursite.com/wp-cron.php every 5 minutes

Code reference: src/Api/AutomationJobs/JobScheduler.php

---

Issue: Automation job timeout / stuck jobs

Symptoms:

• Job shows "In Progress" for hours
• Progress stopped at specific percentage
• Error logs show timeout messages

Cause:

• Job timeout threshold reached (30 minutes)
• Too many products selected for job
• Server resource limits (memory, execution time)

Fix:

1. Wait for automatic recovery:

   • Stuck Job Reaper runs every 2 minutes
   • Automatically reschedules stuck jobs
   • Check back in 5 minutes

2. Reduce job size:

   • Edit job settings
   • Use stricter product filters
   • Process 50-100 products per job maximum
   • Create multiple smaller jobs instead of one large job

3. Check server resources:

   • Contact hosting support
   • Ask about: PHP memory_limit, max_execution_time
   • Recommend: 256MB memory, 300s execution time

4. Stop and restart job:

   • Automation Jobs page
   • Click "Stop Job"
   • Wait 1 minute
   • Click "Resume Job"

Maximum limits:

• Concurrent jobs: 3
• Job timeout: 30 minutes
• Processing interval: 5 minutes

Code reference: src/Api/AutomationJobs/StuckJobReaper.php

---

Issue: Jobs running but drafts not created

Symptoms:

• Job shows completed status
• Progress bar reached 100%
• No drafts in review queue
• No errors in job logs

Cause:

• Job configured to auto-apply (skips draft review)
• Draft creation failed silently
• Database table issue

Fix:

1. Check job settings:

   • Edit automation job
   • Look for "Auto-apply" option
   • If enabled: Content applied directly (no drafts created)
   • This is expected behavior

2. Verify draft review enabled:

   • Job settings → Content Review
   • Enable "Require review before publishing"
   • Save job settings

3. Check job logs:

   • Automation Jobs page → Select job
   • Click "View Logs"
   • Look for error messages
   • Search for: "draft", "error", "failed"

4. Test with new job:

   • Create new automation job
   • Select 1-2 products only
   • Enable draft review
   • Monitor execution

---

Slow Performance

Issue: Generation takes longer than 30 seconds

Symptoms:

• Progress indicator visible for extended time
• Other admin pages load fast, only generation slow
• Eventually succeeds but takes too long

Cause:

• Complex prompts with long templates
• Large product data (many attributes, long descriptions)
• Slow AI provider response (provider-side latency)
• Server connection to AI provider slow

Fix:

1. Simplify prompts:

   • Settings → Prompt Templates
   • Remove unnecessary instructions
   • Keep prompts under 500 words
   • Remove example outputs if included

2. Switch to faster model:

   • Settings → Model Selection
   • OpenAI: Use GPT-3.5 Turbo (faster than GPT-4)
   • Gemini: Use Gemini Flash (faster than Gemini Pro)
   • OpenRouter: Choose models with "fast" in name

3. Reduce product data sent:

   • Don't include full existing description in prompt
   • Limit attribute count
   • Use selective custom variables only

4. Check provider status:

   • See API connection timeout section
   • Provider may be experiencing high load

Expected times:

• GPT-3.5 Turbo: 3-5 seconds
• GPT-4o: 10-15 seconds
• Gemini Flash: 3-5 seconds
• Gemini Pro: 8-12 seconds

---

Issue: Admin dashboard slow after installing plugin

Symptoms:

• WordPress admin pages load slowly
• Product edit page takes 5+ seconds to load
• Doesn't affect frontend (site loads normally)

Cause:

• Asset loading on every admin page (should only load on plugin pages)
• Cron events processing during page load
• Credit sync API call blocking page load

Fix:

1. Check asset loading:

   • Browser DevTools (F12) → Network tab
   • Refresh product edit page
   • Look for: aipt-metabox.js, aipt-toolkit.js
   • Should only load on product edit pages

2. Disable unnecessary features:

   • If not using automation: Don't create jobs
   • If not using credits: Won't impact performance
   • Disable debug mode (Settings → Advanced)

3. Check cron events:

   # Via WP-CLI
   wp cron event list --format=table | grep aipt

   • Should see: aipt_process_automation_jobs, aipt_monitor_automation_jobs
   • If many events: Indicates stuck jobs (see Automation timeout)

4. Clear all caches:

   • WordPress transient cache
   • Object cache (if using Redis/Memcached)
   • Opcode cache (if available)

---

Empty Content Generated

Issue: Content generated successfully but appears empty after applying

Symptoms:

• Generation works, preview shows content
• Click "Apply" and see success message
• Product page shows blank description field
• Metabox shows empty after reload

Cause:

• Content sanitization removed all HTML
• WordPress wp_kses_post filter too strict
• Conflict with security plugin
• Theme or plugin stripping content

Fix:

1. Test with plain text:

   • Use Standard Bulk Generator (no HTML)
   • If plain text works: HTML sanitization issue
   • If plain text fails: deeper problem

2. Check security plugins:

   • Temporarily disable: Wordfence, Sucuri, iThemes Security
   • Try generation again
   • If works: security plugin blocking content
   • Re-enable plugin, adjust settings

3. Verify content in database:

   SELECT post_content FROM wp_posts WHERE ID = [product_id];

   • If content in database: Display issue (theme/plugin)
   • If empty in database: Save operation failed

4. Check error logs:

   • Enable WordPress debug: define('WP_DEBUG', true);
   • Check: wp-content/debug.log
   • Look for: "aipt", "sanitize", "kses"

Code reference: src/Api/RestEndpoints.php (sanitization patterns)

---

Support & Additional Help

Still experiencing issues? Get help from our support team:

Email Support

Free Plan: Community forum only Pro/Business Plans: Priority email support

📧 support@aiforwoo.com

Include in your message:

1. Issue description (what you tried to do, what happened)
2. Error messages (exact text or screenshots)
3. WordPress version
4. WooCommerce version
5. Active plugins list
6. AI provider and model being used

Community Forum

Visit our community forum for:

• Tips from other users
• Feature requests
• General questions

🌐 https://aiforwoo.com/community

System Information

When contacting support, provide this system info:

To get system info:

1. Go to Settings → System Status
2. Click "Copy System Info"
3. Paste into support email

Alternative (manual):

• WordPress version: Dashboard → Updates
• PHP version: Site Health → Info → Server
• AI Product Tools version: Plugins page
• WooCommerce version: WooCommerce → Status

---

Related Resources

• Installation Guide - System requirements and setup
• API Provider Setup - Configure AI providers
• FAQ - Frequently asked questions
• Best Practices - Optimize your workflows

---

Troubleshooting Tips Summary

Systematic approach:

1. Check quick diagnostic checklist (top of page)
2. Find your issue in table of contents
3. Follow step-by-step fix procedure
4. Verify success indicator mentioned
5. If still broken: Contact support with system info