Troubleshooting Guide

Common issues and solutions for WooAI Chatbot Pro developers.

This doc exists because I got tired of answering the same questions in Slack. If you find a new issue + solution, please add it here. Future you will thank you.

1. Installation Issues

Plugin Activation Fails

Symptoms: White screen or PHP fatal error on activation.

Solutions:

// Check PHP version (requires 8.1+)
echo phpversion(); // Must be >= 8.1.0

// Check memory limit
echo ini_get('memory_limit'); // Should be >= 256M

// Verify WooCommerce is active
if ( ! class_exists( 'WooCommerce' ) ) {
    // WooCommerce must be installed and activated first
}

Debug Steps:

1. Enable WP_DEBUG in wp-config.php:

   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   define( 'WP_DEBUG_DISPLAY', false );
   

2. Check /wp-content/debug.log for errors
3. Verify Composer dependencies: composer install --no-dev

Assets Not Loading

Symptoms: Chat widget doesn't appear, admin panel is blank.

Solutions:

# Rebuild assets
cd /path/to/woo-ai-chatbot-pro
npm install
npm run build

# Verify build output
ls -la assets/dist/
# Should contain: admin.js, chat.js, admin.css, chat.css

Common Causes:

• Missing npm run build after git pull
• Node.js version < 18
• Conflicting plugin enqueuing scripts with same handle

2. AI Provider Issues

API Key Validation Fails

Error: Invalid API key or Authentication failed

// Debug API key configuration
$settings = get_option( 'woo_ai_chatbot_settings' );
error_log( 'Provider: ' . $settings['ai_provider'] );
error_log( 'Key set: ' . ( ! empty( $settings['openai_api_key'] ) ? 'yes' : 'no' ) );

// Test API key directly
add_action( 'admin_init', function() {
    $orchestrator = \WooAIChatbot\AI\AIOrchestrator::instance();
    $result = $orchestrator->validate_current_provider();
    if ( is_wp_error( $result ) ) {
        error_log( 'API Error: ' . $result->get_error_message() );
    }
});

Rate Limiting

Error: 429 Too Many Requests

// Check rate limit status
$user_id = get_current_user_id() ?: $_SERVER['REMOTE_ADDR'];
$transient_key = 'wooai_rate_' . md5( $user_id );
$requests = get_transient( $transient_key );
error_log( "Current requests: $requests / 30 per minute" );

// Temporarily increase limit (not recommended for production)
add_filter( 'wooai_rate_limit', fn() => 60 );
add_filter( 'wooai_rate_window', fn() => 120 );

Provider Fallback Not Working

// Debug provider chain
add_action( 'wooai_before_ai_request', function( $provider, $messages ) {
    error_log( "Using provider: " . get_class( $provider ) );
}, 10, 2 );

add_action( 'wooai_provider_fallback', function( $failed_provider, $next_provider, $error ) {
    error_log( "Fallback from {$failed_provider} to {$next_provider}: {$error->get_error_message()}" );
}, 10, 3 );

3. Chat Widget Issues

Widget Not Appearing

Checklist:

1. Check page exclusions in Settings > Display
2. Verify device settings (mobile/desktop)
3. Check theme footer has <?php wp_footer(); ?>

// Debug widget rendering
add_action( 'wp_footer', function() {
    error_log( 'wp_footer fired' );
    $settings = get_option( 'woo_ai_chatbot_settings' );
    error_log( 'Widget enabled: ' . ( $settings['enabled'] ?? 'not set' ) );
}, 1 );

// Check if widget script is enqueued
add_action( 'wp_print_scripts', function() {
    global $wp_scripts;
    $is_enqueued = wp_script_is( 'woo-ai-chatbot-widget', 'enqueued' );
    error_log( "Widget script enqueued: " . ( $is_enqueued ? 'yes' : 'no' ) );
});

Widget Styling Conflicts

/* Reset conflicting theme styles */
#woo-ai-chatbot-widget {
    all: initial;
    font-family: inherit;
}

/* Increase specificity */
body #woo-ai-chatbot-widget .chat-message {
    /* Your overrides */
}

// Dequeue conflicting styles
add_action( 'wp_enqueue_scripts', function() {
    wp_dequeue_style( 'conflicting-plugin-css' );
}, 100 );

Messages Not Sending

// Debug in browser console
window.WooAIChatbot.debug = true;

// Check nonce
console.log('Nonce:', window.wooAiChatbot?.nonce);

// Manual API test
fetch('/wp-json/woo-ai/v1/chat/message', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-WP-Nonce': window.wooAiChatbot.nonce
    },
    body: JSON.stringify({
        session_id: 'test-session-123',
        message: 'Hello'
    })
}).then(r => r.json()).then(console.log);

4. Playbook Issues

Playbook Not Triggering

// Debug playbook matching
add_filter( 'wooai_playbook_match_debug', '__return_true' );

add_action( 'wooai_playbook_match_result', function( $playbook_id, $matched, $context ) {
    error_log( "Playbook {$playbook_id} matched: " . ( $matched ? 'yes' : 'no' ) );
    error_log( "Context: " . print_r( $context, true ) );
});

// Check playbook status
$playbook = get_post( $playbook_id );
error_log( "Status: {$playbook->post_status}" ); // Must be 'publish'

Step Execution Errors

// Log step execution
add_action( 'wooai_playbook_step_execute', function( $step, $state ) {
    error_log( "Executing step: {$step['id']} type: {$step['type']}" );
}, 10, 2 );

add_action( 'wooai_playbook_step_error', function( $step, $error ) {
    error_log( "Step error: {$step['id']} - {$error->getMessage()}" );
}, 10, 2 );

5. Database Issues

Tables Not Created

// Manually run table creation
$activator = new \WooAIChatbot\Activator();
$activator->create_tables();

// Check if tables exist
global $wpdb;
$tables = [
    $wpdb->prefix . 'wooai_conversations',
    $wpdb->prefix . 'wooai_messages',
    $wpdb->prefix . 'wooai_analytics'
];
foreach ( $tables as $table ) {
    $exists = $wpdb->get_var( "SHOW TABLES LIKE '$table'" ) === $table;
    error_log( "$table exists: " . ( $exists ? 'yes' : 'no' ) );
}

Session Data Loss

// Check session storage
$session_id = 'your-session-id';
global $wpdb;
$session = $wpdb->get_row( $wpdb->prepare(
    "SELECT * FROM {$wpdb->prefix}wooai_conversations WHERE session_id = %s",
    $session_id
));
error_log( "Session: " . print_r( $session, true ) );

// Clear stale sessions (run via WP-CLI or cron)
$wpdb->query( $wpdb->prepare(
    "DELETE FROM {$wpdb->prefix}wooai_conversations WHERE updated_at < %s",
    date( 'Y-m-d H:i:s', strtotime( '-7 days' ) )
));

6. Performance Issues

Slow AI Responses

// Profile AI request time
add_action( 'wooai_before_ai_request', function() {
    defined( 'WOOAI_REQUEST_START' ) || define( 'WOOAI_REQUEST_START', microtime( true ) );
});

add_action( 'wooai_after_ai_response', function( $response ) {
    $duration = microtime( true ) - WOOAI_REQUEST_START;
    error_log( "AI request took: {$duration}s" );
    if ( $duration > 5 ) {
        error_log( "WARNING: Slow AI response. Consider caching or reducing context." );
    }
});

High Memory Usage

// Monitor memory
add_action( 'wooai_before_ai_request', function() {
    error_log( 'Memory before: ' . memory_get_usage( true ) / 1024 / 1024 . 'MB' );
});

add_action( 'wooai_after_ai_response', function() {
    error_log( 'Memory after: ' . memory_get_usage( true ) / 1024 / 1024 . 'MB' );
    error_log( 'Peak memory: ' . memory_get_peak_usage( true ) / 1024 / 1024 . 'MB' );
});

7. Common Error Codes

8. Debug Mode

Enable comprehensive debugging:

// wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WOOAI_DEBUG', true );
define( 'WOOAI_LOG_AI_REQUESTS', true ); // Logs full AI requests/responses

// Browser console
localStorage.setItem('wooai_debug', 'true');

9. "I tried everything and it still doesn't work"

Real cases from production that took forever to debug:

Case 1: Widget worked locally, broken on staging

• Cause: Cloudflare Rocket Loader was rewriting our JS
• Fix: Added data-cfasync="false" to script tag

Case 2: Chat worked, but products never showed

• Cause: WooCommerce REST API was disabled by security plugin (Wordfence)
• Fix: Whitelist /wp-json/wc/v3/* in Wordfence settings

Case 3: AI responses were always in English despite Ukrainian UI

• Cause: System prompt didn't include language instruction
• Fix: Added wooai_system_prompt filter with Respond in {locale} - see hooks doc

Case 4: Memory leak on high-traffic site (5k+ sessions/day)

• Cause: Sessions weren't being cleaned up
• Fix: Added WP-Cron job to purge sessions older than 7 days

10. Getting Help

1. Check logs: /wp-content/debug.log
2. Browser console: F12 > Console tab
3. Network tab: Check API responses
4. GitHub Issues: Report bugs
5. Slack: #wooai-dev channel (internal team only)