🔧 Troubleshooting Guide

🚨 Common Issues & Solutions

❌ API Key Issues

Problem: "Invalid API key" or "API key not configured" errors

Solutions:

Verify API key has been generated from Google Studio API
Verify API key is correctly entered in QuarkCode AI → Settings
Ensure API key has Gemini API access enabled in Google Cloud Console
Check for extra spaces or hidden characters in the API key
Confirm billing is enabled in your Google Cloud project
Test API key using Google's API explorer

                    # Test API key manually:
                    curl -H "Content-Type: application/json" \
                    -d '{"prompt":"test"}' \
                    "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=YOUR_API_KEY"
                

❌ Image Generation Failures

Problem: Images fail to generate or show error messages

Solutions:

Check if user has sufficient token balance
Verify rate limits haven't been exceeded (hourly/daily/monthly)
Ensure prompts don't contain prohibited content
Check server memory limits (increase to 256MB+ if needed)
Verify cURL is enabled on your server
Test with simpler prompts first

⚠️ Token System Issues

Problem: Token deduction not working or incorrect balances

Solutions:

Check database table `wp_quarkcode_token_log` exists
Verify user meta table has token balance entries
Clear any caching plugins that might affect user data
Check for JavaScript errors in browser console
Ensure AJAX requests are not being blocked

                    # Check token balance manually:
                    SELECT meta_value FROM wp_usermeta 
                    WHERE user_id = USER_ID AND meta_key = 'quarkcode_tokens';
                

🔍 Diagnostic Tools

Enable Debug Mode

Add these lines to your wp-config.php for detailed logging:

                define('WP_DEBUG', true);
                define('WP_DEBUG_LOG', true);
                define('QUARKCODE_DEBUG', true);
            

Server Requirements Check

Requirement	Minimum	Recommended	Check Method
PHP Version	7.4	8.0+	phpinfo() or Site Health
Memory Limit	128MB	256MB+	WP Admin → Tools → Site Health
Max Execution Time	30s	60s+	Check php.ini settings
cURL Extension	Required	Latest	extension_loaded('curl')
OpenSSL	Required	Latest	For HTTPS API calls

🚦 Error Code Reference

Error Code: QC_001 - API Connection Failed

Cause: Cannot connect to Google Gemini API

Solutions:

Check server firewall settings
Verify outbound HTTPS connections are allowed
Test network connectivity to googleapis.com
Check for proxy or CDN interference

Error Code: QC_002 - Insufficient Tokens

Cause: User doesn't have enough tokens for generation

Solutions:

Add tokens manually via admin panel
Check WooCommerce token products configuration
Verify token deduction settings are correct

Error Code: QC_003 - Rate Limit Exceeded

Cause: User has exceeded hourly/daily/monthly limits

Solutions:

Wait for rate limit reset
Adjust rate limits in settings
Implement queuing system for high-volume users

📋 Pre-Support Checklist

Before contacting support, please verify:

✅ WordPress and plugin are updated to latest versions
✅ No plugin conflicts (test with other plugins deactivated)
✅ Theme compatibility (test with default WordPress theme)
✅ Server requirements are met
✅ API key is valid and has proper permissions
✅ Debug logs have been checked for specific errors