Troubleshooting
Solve common issues and optimize performance
Common Issues & Solutions
Issue 1: Rules Not Triggering
Symptoms:
– Customer can checkout with invalid cart
– No error messages displayed
– No violations logged in analytics
Cause A: Rule Not Active
Check:
1. Go to Cart Guard → Rules
2. Find your rule in the table
3. Look at "Status" column
4. If shows "Inactive", rule is disabled
Solution:
1. Click rule name to open editor
2. Scroll to "Rule Status" toggle
3. Switch from "Inactive" to "Active"
4. Click "Save Changes"
5. Test cart validation again
Cause B: API Connection Failed
Check:
1. Go to Cart Guard → Settings
2. Look for connection status banner
3. Should show: "✅ API Connected"
4. If shows: "⚠️ API Connection Error", follow steps below
Solution:
1. Verify license key entered correctly:
- Settings → License Key field
- Copy/paste from purchase email (avoid typos)
- Click "Save Changes"
2. Check server firewall:
- Ask hosting provider: "Does firewall allow outbound HTTPS?"
- Required domain: api.paretoedge.com
- Port: 443 (HTTPS)
3. Test connection:
- Settings → "Test API Connection" button
- Success: "✅ Connected"
- Failure: Copy error message → Email [email protected]
Cause C: Soft-Fail Mode Enabled
When soft-fail mode is active, validations log violations but don’t block checkout.
Check:
1. Go to Cart Guard → Settings
2. Find "Enable Soft-Fail Mode" checkbox
3. If checked, cart validations pass automatically
Solution:
1. Uncheck "Enable Soft-Fail Mode"
2. Click "Save Settings"
3. Test cart validation (should now block invalid checkout)
When to Use Soft-Fail:
– Testing new rules (log violations without blocking)
– High-traffic periods (Black Friday, avoid false blocks)
– API issues (temporary fallback to protect revenue)
Cause D: Product IDs Wrong
Rules must reference correct product IDs/SKUs.
Check:
1. Edit rule → Product Selection step
2. Verify products listed correctly
3. Click product name → Confirm matches intended product
Solution:
1. Delete incorrect products (X button)
2. Re-add using product search:
- Type product name or SKU
- Select correct product from dropdown
- Verify product appears in list
3. Save rule
4. Test validation (add actual product to cart)
Tip: Use SKU search instead of product name (more accurate)
Issue 2: Checkout Button Not Disabled
Symptoms:
– Error message shows on cart page
– But “Proceed to Checkout” button still clickable
– Customer can reach checkout page despite violation
Cause A: JavaScript Not Loading
Check:
1. Open browser console (F12 → Console tab)
2. Look for errors mentioning "pcg" or "cart-guard"
3. If see error: "pcg-frontend.js not found"
Solution:
1. Clear WordPress cache:
- WP Super Cache: Settings → Delete Cache
- W3 Total Cache: Performance → Empty All Caches
- WP Rocket: Settings → Clear Cache
2. Regenerate assets:
- Cart Guard → Settings
- Scroll to "Advanced" section
- Click "Regenerate Assets" button
- Wait for success message
3. Hard refresh browser:
- Windows: Ctrl + Shift + R
- Mac: Cmd + Shift + R
4. Test checkout button (should now disable when error shown)
Cause B: Theme Conflicts
Some themes override WooCommerce cart templates incorrectly.
Test for Theme Conflict:
1. Go to Appearance → Themes
2. Activate "Twenty Twenty-Four" (default WordPress theme)
3. Test cart validation
4. If works with default theme, theme conflict confirmed
Solution:
Option 1: Contact theme developer
- Theme name & version
- Issue: "Cart Guard checkout button disabling not working"
- Request: Compatibility update
Option 2: Custom CSS workaround
- Cart Guard → Settings → Custom CSS field
- Add:
.woocommerce-cart .checkout-button:disabled {
pointer-events: none !important;
opacity: 0.5 !important;
}
- Save settings
Cause C: Plugin Conflicts
Certain plugins bypass standard WooCommerce cart flow.
Common Conflicts:
– AJAX Cart plugins (bypass validation)
– Mini cart widgets (separate checkout buttons)
– One-click checkout plugins (skip cart page)
Solution:
1. Go to Plugins → Installed Plugins
2. Identify suspect plugins (AJAX cart, mini cart)
3. Deactivate one plugin at a time
4. Test cart validation after each deactivation
5. When validation works, conflict found
6. Choose:
- Keep Cart Guard, remove conflicting plugin
- Contact plugin developer for compatibility
- Try alternative plugin
Issue 3: Discounts Not Applying
Symptoms:
– Bundle rule active with discount configured
– Products in cart satisfy bundle requirements
– But discount not showing on cart page
Cause A: WooCommerce Caching
Cart discounts cached until cart refreshed.
Solution:
1. Clear cart completely (remove all items)
2. Clear browser cookies:
- Chrome: Settings → Privacy → Clear browsing data
- Firefox: Settings → Privacy → Clear cookies
3. Clear WordPress cache (if using cache plugin)
4. Add products to cart again (fresh session)
5. Discount should now appear
Cause B: Coupon Conflicts
Some coupon codes block other discounts from stacking.
Check:
1. Look at cart page → Coupon code section
2. If customer applied coupon code, potential conflict
Solution:
Option 1: Remove coupon and test
1. Remove customer's coupon code
2. Refresh cart page
3. If bundle discount now appears, coupon was blocking it
Option 2: Configure coupon to allow stacking
1. WooCommerce → Coupons → Edit coupon
2. Go to "Usage Restrictions" tab
3. Uncheck "Individual use only"
4. Save coupon
5. Test with both coupon + bundle discount
Cause C: Discount Type Mismatch
Discount settings may be incomplete or incorrect.
Check:
1. Edit rule → Advanced Options tab
2. Review discount configuration:
- Discount Type: Selected (not "None")
- Discount Value: Number entered (not blank/0)
- Products: Correct bundle items selected
Solution:
1. Discount Type: Select "Percentage" or "Fixed Amount"
2. Discount Value: Enter number (e.g., 10 for 10%)
3. Save rule
4. Clear cart and test again
Issue 4: Yellow Badge Orders Not Showing
Symptoms:
– Soft-fail violations happening (API logs confirm)
– But no yellow badges on orders list
– Orders appear with no Cart Guard status column
Cause A: Screen Options Hidden
WooCommerce allows hiding columns via Screen Options.
Solution:
1. Go to WooCommerce → Orders
2. Click "Screen Options" (top right corner, small tab)
3. Dropdown appears showing all columns
4. Check "Cart Guard" column checkbox
5. Click away to close Screen Options
6. Cart Guard column should now appear
Cause B: HPOS Migration
WooCommerce 8.2+ introduced High-Performance Order Storage (HPOS).
Check:
1. WooCommerce → Settings → Advanced → Features
2. Look for "High-Performance Order Storage" option
3. If enabled, Cart Guard requires update
Solution:
1. Go to Plugins → Installed Plugins
2. Check Cart Guard version (need v3.1.0+ for HPOS)
3. If older version, click "Update Now"
4. Refresh orders list
5. Badges should now appear
Cause C: Admin Columns Plugin
Some admin column plugins override WooCommerce columns.
Solution:
If using "Admin Columns" plugin:
1. WooCommerce → Settings → Admin Columns
2. Find "Orders" column configuration
3. Click "Add Column" → Select "Cart Guard"
4. Drag Cart Guard column to desired position
5. Save settings
6. Refresh orders list
Issue 5: Import Failed (Compatible Plugins)
Symptoms:
– Import button clicked
– “Import Failed” or “0 rules imported” message
– Expected rules not appearing in Cart Guard
Cause A: Source Plugin Not Active
Cart Guard reads rules from source plugin database tables.
Solution:
1. Go to Plugins → Installed Plugins
2. Verify source plugin is active:
- Force Sells for WooCommerce
- WPC Product Bundles
- Chained Products for WooCommerce
3. If inactive, click "Activate"
4. Return to Cart Guard → Rules
5. Retry import
Cause B: No Rules to Import
Source plugin may not have any configured rules.
Check:
Force Sells:
1. Products → Edit any product
2. Look for "Force Sells" tab
3. Check if products added
WPC Bundles:
1. Products → Edit any product
2. Look for "Bundled Products" tab
3. Check if bundle configured
Chained Products:
1. Products → Edit any product
2. Look for "Chained Products" metabox
3. Check if chains configured
Solution:
If no rules exist:
1. Create 1-2 sample rules in source plugin
2. Retry Cart Guard import
3. If import succeeds, add remaining rules
Cause C: Database Compatibility
Rare: Cart Guard tables may be corrupted/missing.
Solution:
1. Go to Cart Guard → Settings
2. Scroll to "Advanced" section
3. Click "Reset Database Tables" button
4. Confirm action (won't delete rules, just recreates tables)
5. Retry import
6. If still fails, contact support with PHP error log
Error Messages Explained
“API Connection Failed”
Full Message:
⚠️ Cart Guard API Connection Failed
Unable to reach validation server. Soft-fail mode activated.
Cart validations will pass until connection restored.
What It Means:
– WordPress can’t reach Cart Guard API server
– Soft-fail mode protecting revenue (checkouts allowed)
– Violations not being logged until reconnected
Possible Reasons:
1. API Server Maintenance (rare, 99.9% uptime SLA)
2. Firewall Blocking Outbound HTTPS (check with host)
3. License Key Invalid/Expired (verify in Settings)
4. Temporary Network Issue (retry in 5 minutes)
Action Steps:
1. Wait 5 minutes, refresh Settings page
2. If persists, check status page: status.paretoedge.com
3. Contact support if outage exceeds 30 minutes
4. Meanwhile: Soft-fail protects revenue (no lost sales)
“Rate Limit Exceeded”
Full Message:
⚠️ Monthly API Call Limit Reached
You've used 100,347 of 100,000 calls this month (PRO tier).
Soft-fail mode activated until limit resets on Dec 1, 2025.
[Upgrade to AGENCY] [View Usage Details]
What It Means:
– You exceeded monthly API call allocation for your tier
– Cart validations still work (soft-fail mode)
– Violations not logged until next month reset
Action Steps:
Option 1: Upgrade Tier (Instant)
1. Click "Upgrade to AGENCY" button
2. Pay prorated difference
3. New limits active immediately:
- AGENCY: 1,000,000 calls/month (10x increase)
- Cost: $499/year
Option 2: Wait for Reset
Limit resets: First day of next month (12:00 AM UTC)
Current date: Nov 14 → Reset: Dec 1 (17 days)
Meanwhile: Soft-fail protects revenue (no lost sales)
Option 3: Reduce Call Volume
1. Review rule triggers (too broad?)
2. Deactivate non-critical rules temporarily
3. See "Performance Optimization" section below
“Rule Evaluation Error”
Full Message:
❌ Rule Evaluation Failed
Technical error processing rule "Coffee + Mug BOGO"
Error: Invalid condition format in conditions_json
[View Error Details] [Contact Support]
What It Means:
– Specific rule has configuration error
– That rule not enforcing (other rules still work)
– Soft-fail logged for affected orders
Action Steps:
Step 1: Edit Rule
1. Go to Cart Guard → Rules
2. Find rule mentioned in error
3. Click "Edit"
4. Review all fields for errors:
- Missing products (product search)
- Invalid discount value (text instead of number)
- Blank required fields (rule name, message)
Step 2: Recreate Rule
If editing doesn't fix:
1. Export rule as JSON (backup via browser console)
2. Delete problematic rule
3. Create new rule using wizard
4. Test validation
Step 3: Contact Support
If persists:
1. Click "View Error Details" button
2. Copy full error message
3. Email [email protected] with:
- Error message (full text)
- Rule name
- Screenshot of rule configuration
- Expected behavior vs actual behavior
Performance Optimization
Slow Cart Page Loading
Symptoms:
– Cart page takes 3-5 seconds to load
– “Thinking” spinner visible for multiple seconds
– Customer complaints about checkout speed
Solution 1: Enable Object Caching
Recommended: Redis or Memcached
WordPress Plugins:
– Redis Object Cache (free)
– WP Redis (free)
Setup:
1. Ask hosting provider to install Redis on server
2. Install "Redis Object Cache" plugin
3. Go to Settings → Redis
4. Click "Enable Object Cache"
5. Test cart page load time (should improve 50-70%)
Expected Results:
– Before: 3-5 seconds cart page load
– After: 0.5-1.5 seconds cart page load
Solution 2: Reduce Active Rules
Every rule adds validation logic. Fewer rules = faster validation.
Goal: Keep active rules under 50
Review Process:
1. Go to Cart Guard → Analytics
2. Sort rules by "Trigger Count" (last 30 days)
3. Identify rarely-triggered rules (<10 triggers/month)
4. Deactivate low-performing rules
5. Archive seasonal rules when not needed
Example:
Before: 75 active rules
Triggers/month: 20 rules have <10 triggers (nearly unused)
Action: Deactivate those 20 rules
After: 55 active rules, 25% faster validation
Solution 3: Optimize Rule Conditions
Bad: Rule checks ALL products in catalog
Good: Rule checks specific category/tag only
Example:
Rule: "Wholesale minimum 10 units"
Before (slow):
- Applies to: All Products (checks entire catalog)
- Performance: 200-300ms validation
After (fast):
- Applies to: "Wholesale" category only
- Performance: 50-80ms validation
How to Optimize:
1. Edit rule → Product Selection step
2. Change from "All Products" to specific category
3. Or use product tags: "wholesale", "bulk", etc.
4. Save rule
5. Test cart page load time
High API Call Usage
Symptoms:
– Approaching monthly API call limit quickly
– Usage growing faster than order volume
– Frequent limit exceeded warnings
Solution 1: Identify High-Traffic Pages
Check Google Analytics:
1. Behavior → Site Content → All Pages
2. Filter by "/cart" page
3. Check daily pageviews
4. If unusually high (10,000+/day), investigate:
- Bots crawling cart page?
- Abandoned carts refreshing repeatedly?
Optimization:
Disable validation for empty carts:
1. Add to child theme functions.php:
add_filter('pcg_skip_validation', function($skip, $cart) {
return empty($cart) || count($cart->get_cart()) === 0;
}, 10, 2);
Result: No API calls for empty carts (saves 20-30%)
Solution 2: Disable AJAX Validation for Guests
Guests account for 70-80% of traffic but <20% of conversions.
Add to functions.php:
add_filter('pcg_validate_for_guest', '__return_false');
Result:
– Only validate at checkout (not on cart page updates)
– Reduces API calls by 40-60%
– Guest checkout still validated (no bypass)
Solution 3: Batch Validation Requests
For high-traffic stores (1000+ orders/day):
Contact Support:
Email: [email protected]
Subject: "Enterprise optimization - batch validation"
Include: Daily order volume, current API usage
What We’ll Do:
– Enable batch validation endpoint (multiple carts in one API call)
– Reduces API call count by 50%
– No changes to your rules or configuration
– Available for AGENCY tier only
“`
Next Steps
Now that you can troubleshoot issues:
Last Updated: November 14, 2025
Plugin Version: 1.0