# Card Oracle Troubleshooting Guide

This guide helps you to diagnose and resolve common issues with the Card Oracle Premium plugin.

## Table of Contents

1. [Quick Diagnostics](#quick-diagnostics)
2. [Reading Display Issues](#reading-display-issues)
3. [Content and Data Issues](#content-and-data-issues)
4. [Layout and Styling Issues](#layout-and-styling-issues)
5. [Premium Feature Issues](#premium-feature-issues)
6. [Payment Issues](#payment-issues)
7. [Email Integration Issues](#email-integration-issues)
8. [Performance Issues](#performance-issues)
9. [Debug Logging](#debug-logging)
10. [Error Messages Reference](#error-messages-reference)
11. [Contacting Support](#contacting-support)

---

## Quick Diagnostics

### Using the Status Tab

The Status tab provides comprehensive diagnostics:

1. Go to **Card Oracle > Dashboard > Status**
2. Review the following sections:

| Section | What to Check |
|---------|---------------|
| System Information | WordPress version, PHP version, memory limit |
| Card Oracle Status | Plugin version, license status, log directory |
| Post Type Counts | Readings, positions, cards, descriptions totals |
| Error Logs | Recent errors and warnings |

### Quick Health Check

Run through this checklist:

- [ ] Plugin is activated
- [ ] Reading is published (not draft)
- [ ] Positions have Order values set
- [ ] Cards have featured images
- [ ] Descriptions link correct cards to positions
- [ ] Premium license is connected (if using premium features)

---

## Reading Display Issues

### Reading Not Appearing in Dropdown

Before doing anything else, go to the Card Oracle > Validation tab and check for errors there. If nothing shows up on the Validation tab, run through the options below.

**Symptoms:**
- Reading missing from Gutenberg block dropdown
- Reading not found by shortcode

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| Reading is in draft status | Publish the reading |
| Reading is in trash | Restore from trash |
| REST API disabled | Check for plugins blocking REST API |
| Caching issue | Clear site cache and browser cache |

**Verification:**
```
Go to Card Oracle > Readings
Confirm the reading shows "Published" status
```

### Reading Shows "No Reading Found"

**Symptoms:**
- Shortcode displays error message
- Empty content on frontend

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| Wrong slug in shortcode | Verify slug matches reading URL |
| Wrong ID in shortcode | Check reading ID in admin URL |
| Reading deleted | Create new reading or restore from backup |

**Finding the correct slug:**
1. Edit the reading
2. Look at the URL: `post.php?post=123&action=edit`
3. The slug is in the Permalink section

### Cards Not Displaying

**Symptoms:**
- Reading loads but no cards appear
- Deck area is empty

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| No cards linked to reading | Create cards with this reading's ID |
| JavaScript error | Check browser console (F12) for errors |
| CSS conflict | Test with default theme |
| Missing assets | Run `gulp compile_js` to rebuild |

---

## Content and Data Issues

### Positions Out of Order

**Symptoms:**
- Cards appear in wrong sequence
- Position numbers don't match display order

**Solution:**
1. Go to **Card Oracle > Positions**
2. Filter by the affected reading
3. Edit each position
4. Set the **Order** field correctly (1, 2, 3, etc.)
5. Save each position

**Prevention:**
- Always set Order values when creating positions
- Use the Wizard which auto-assigns order values

### Descriptions Not Showing

**Symptoms:**
- Card appears but no interpretation text
- "No description available" message

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| Missing description post | Create description linking card to position |
| Wrong card selected in description | Edit description, select correct card |
| Wrong position selected in description | Edit description, select correct position |
| Description in draft status | Publish the description |

**Verification:**
1. Go to **Card Oracle > Descriptions**
2. Filter by reading
3. Confirm descriptions exist for all card-position combinations
4. For a 10-card, 10-position reading, you need 100 descriptions

### Reversed Descriptions Not Appearing

**Symptoms:**
- Only upright meanings show
- Reversed field is empty or hidden

**Causes:**
- Free version: Reversed descriptions are premium-only
- Premium: Reversed description field is empty
- Premium: Reverse percentage set to 0

**Solutions:**
1. Activate premium license for reversed feature
2. Edit each description and fill in reversed meaning
3. Set reverse percentage > 0 in reading settings

### Featured Images Not Displaying

**Symptoms:**
- Card placeholder instead of image
- Broken image icons

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| No featured image set | Edit card, set featured image |
| Image deleted from media library | Re-upload and reassign |
| Wrong image permissions | Check file permissions (644) |
| CDN or cache issue | Purge CDN/cache |

---

## Layout and Styling Issues

### Layout Broken or Misaligned

**Symptoms:**
- Cards overlapping incorrectly
- Text outside containers
- Responsive issues on mobile

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| Theme CSS conflict | Add custom CSS to override conflicts |
| Missing plugin CSS | Check that CSS files load in source |
| JavaScript not loading | Check for JS errors in console |
| Old cached CSS | Clear cache, force reload (Ctrl+Shift+R) |

**Testing:**
1. Switch to a default theme (Twenty Twenty-Four)
2. Deactivate other plugins temporarily
3. If issue resolves, conflict is with theme/plugin

### Premium Layouts Not Available

**Symptoms:**
- Circular/Spread layouts not in dropdown
- Premium layout options hidden

**Solutions:**
1. Go to **Card Oracle > Account**
2. Verify license is active
3. If expired, renew license
4. Clear any caching plugins

### Mobile Display Issues

**Symptoms:**
- Reading unusable on mobile devices
- Cards too small to tap
- Content overflows screen

**Solutions:**
1. Switch to "Mobile" presentation layout
2. Use responsive-friendly deck layout (Standard or Overlapping)
3. Check theme's responsive CSS
4. Test with viewport meta tag present

---

## Premium Feature Issues

### License Not Recognized

**Symptoms:**
- Premium features locked
- "Upgrade to Premium" messages
- License shows as inactive

**Solutions:**
1. Go to **Card Oracle > Account**
2. Click **Sync License**
3. If needed, disconnect and reconnect account
4. Check license hasn't expired
5. Verify site URL matches license domain

### Premium Code Not Loading

**Symptoms:**
- Premium PHP files not executing
- `can_use_premium_code__premium_only()` returns false

**Diagnostic:**
```php
// Add to functions.php temporarily
add_action('admin_notices', function() {
    if (function_exists('card_oracle_fs')) {
        $can_use = card_oracle_fs()->can_use_premium_code__premium_only();
        echo '<div class="notice notice-info"><p>Premium: ' .
             ($can_use ? 'Active' : 'Inactive') . '</p></div>';
    }
});
```

**Solutions:**
1. Ensure premium files exist in plugin directory
2. Files should end with `__premium_only.php`
3. Re-download and re-install plugin if files missing
4. Contact support if license issues persist

---

## Payment Issues

### PayPal Payment Form Not Showing

**Symptoms:**
- Reading displays without payment option
- No PayPal button visible

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| No price set | Edit reading, set price in meta box |
| Premium not active | Activate premium license |
| PayPal not configured | Add credentials in Dashboard > Payment Provider |
| Sandbox mode mismatch | Match sandbox setting to credentials |

### PayPal Payment Fails

**Symptoms:**
- Error during checkout
- Payment not completing
- IPN not received

**Diagnostic Steps:**
1. Enable debug logging
2. Check error logs for PayPal errors
3. Verify credentials in Dashboard > Payment Provider
4. Test in sandbox mode first

**Common Issues:**

| Issue | Solution |
|-------|----------|
| Invalid credentials | Re-enter API credentials from PayPal |
| IPN URL not accessible | Ensure site is publicly accessible |
| SSL required | Use HTTPS for payment pages |
| Currency mismatch | Match currency setting to PayPal account |

### Stripe Payment Form Not Showing

**Symptoms:**
- No Stripe checkout option
- Payment form missing

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| Keys not configured | Add keys in Dashboard > Payment Provider |
| Wrong key type | Use publishable key (starts with pk_) |
| JavaScript error | Check console for Stripe.js errors |
| Domain not verified | Add domain in Stripe dashboard |

### Stripe Payment Fails

**Symptoms:**
- Card declined errors
- Webhook failures
- Payment intent errors

**Diagnostic Steps:**
1. Check Stripe dashboard for error details
2. Verify webhook endpoint is configured
3. Test with Stripe test cards
4. Check debug logs

**Common Issues:**

| Issue | Solution |
|-------|----------|
| Webhook not configured | Add endpoint in Stripe dashboard |
| Secret key exposed | Never use secret key in frontend |
| 3D Secure required | Ensure checkout handles authentication |
| Test/Live mode mismatch | Match keys to mode setting |

### Purchased Reading Record Not Created After Payment

**Symptoms:**
- Payment successful but no Purchased Reading record
- Reading not unlocking
- Customer not receiving email

**Diagnostic Steps:**
1. Check **Card Oracle > Purchased Readings** for pending entries
2. Review error logs for order creation failures
3. Verify webhook/IPN processing
4. Check Purchased Reading post type permissions

---

## Email Integration Issues

### Emails Not Sending

**Symptoms:**
- Customer not receiving reading email
- No delivery confirmation

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| Email not configured | Set up in Dashboard > Integrations |
| SMTP issues | Use an SMTP plugin (WP Mail SMTP) |
| Email in spam | Check spam folder, configure SPF/DKIM |
| Integration not set up | Configure MailChimp/AC/Brevo |

**Testing:**
1. Enable debug logging
2. Complete a test reading
3. Check logs for email errors
4. Verify email appears in integration dashboard

### MailChimp Integration Failing

**Symptoms:**
- Contacts not syncing
- API errors in logs

**Solutions:**
1. Verify API key is correct
2. Check API key has sufficient permissions
3. Confirm list/audience exists
4. Check MailChimp API status

**Testing API Key:**
1. Log into MailChimp
2. Go to Account > Extras > API keys
3. Generate new key if needed
4. Test with MailChimp API playground

### ActiveCampaign Integration Failing

**Symptoms:**
- Contacts not added
- Automation not triggering

**Solutions:**
1. Verify API URL format (https://yourname.api-us1.com)
2. Check API key permissions
3. Confirm list exists and is active
4. Review ActiveCampaign API logs

### Brevo Integration Failing

**Symptoms:**
- Contacts not syncing
- API authentication errors

**Solutions:**
1. Verify API key (v3 key required)
2. Check contact list exists
3. Confirm API key has correct permissions
4. Review Brevo transactional email settings
5. Ensure that your IP address is authorized on Brevo (Settings - Security)

---

## Performance Issues

### Slow Page Load

**Symptoms:**
- Reading takes long to display
- Page timeout errors
- High server load

**Causes and Solutions:**

| Cause | Solution |
|-------|----------|
| Large number of cards | Optimize queries, use caching |
| Unoptimized images | Compress and resize card images |
| No caching | Enable WordPress caching plugin |
| Too many descriptions | Consider pagination or lazy loading |

**Optimization Steps:**
1. Enable transient caching in Settings
2. Use an object cache (Redis/Memcached)
3. Optimize images (max 300KB per card)
4. Use a CDN for assets

### Database Query Slow

**Symptoms:**
- Admin pages loading slowly
- Timeout during reading display

**Diagnostic:**
1. Enable `SAVEQUERIES` in wp-config.php
2. Check for slow queries in debug bar
3. Review database indexes

**Solutions:**
1. Ensure database tables are optimized
2. Add indexes if missing
3. Consider database cleanup
4. Upgrade hosting if needed

### Memory Limit Errors

**Symptoms:**
- "Allowed memory size exhausted" error
- White screen of death
- Incomplete page loads

**Solutions:**

1. Increase WordPress memory limit in wp-config.php:
```php
define('WP_MEMORY_LIMIT', '256M');
```

2. Increase PHP memory limit in php.ini:
```ini
memory_limit = 256M
```

3. Or in .htaccess:
```apache
php_value memory_limit 256M
```
---

## Error Messages Reference

### Common Error Messages

| Error | Meaning | Solution |
|-------|---------|----------|
| "Reading not found" | Invalid slug or ID | Verify reading exists and is published |
| "No cards available" | No cards linked to reading | Create cards with this reading ID |
| "Description not found" | Missing card-position pair | Create description entry |
| "Payment failed" | Transaction error | Check payment credentials and logs |
| "API key invalid" | Wrong integration key | Re-enter correct API key |
| "Memory exhausted" | PHP memory limit hit | Increase memory limit |
| "Permission denied" | File permission issue | Fix directory permissions |
| "License expired" | Premium license issue | Renew or activate license |

### HTTP Error Codes

| Code | Meaning | Solution |
|------|---------|----------|
| 403 | Forbidden | Check file permissions, security plugin |
| 404 | Not found | Verify REST endpoints, permalinks |
| 500 | Server error | Check error logs, increase memory |
| 503 | Service unavailable | Server overloaded, contact host |

---

## Contacting Support

### Before Contacting Support

Gather this information:
1. WordPress version
2. Card Oracle version
3. PHP version
4. Error messages (exact text)
5. Steps to reproduce the issue
6. Screenshots if applicable
7. Debug log export

### Generating a System Report

1. Go to **Card Oracle > Dashboard > Status**
2. Click **Email System Report** or copy the displayed information
3. Include in your support request

### Support Channels

- **Email**: support@chillichalli.com
- **Documentation**: This troubleshooting guide and related docs
- **Freemius Support**: For license-specific issues

### What to Include in Support Requests

1. **Subject**: Clear description of issue
2. **Environment**: WordPress version, PHP version, theme
3. **Steps**: How to reproduce the problem
4. **Expected**: What should happen
5. **Actual**: What actually happens
6. **Logs**: Relevant error log entries
7. **Screenshots**: Visual evidence of issue

---

## Quick Reference Checklist

### Reading Not Working

- [ ] Reading is published
- [ ] Shortcode has correct slug/ID
- [ ] Positions exist with Order values
- [ ] Cards exist with featured images
- [ ] Descriptions link cards to positions
- [ ] JavaScript loads without errors
- [ ] CSS loads correctly
- [ ] Cache is cleared

### Premium Features Not Working

- [ ] License is active and connected
- [ ] Site URL matches license domain
- [ ] Premium files present in plugin
- [ ] can_use_premium_code returns true
- [ ] Cache cleared after license change

### Payments Not Working

- [ ] Premium license active
- [ ] Reading has price set
- [ ] Payment gateway configured
- [ ] Credentials are correct
- [ ] Sandbox/Live mode matches credentials
- [ ] Webhook/IPN URL accessible
- [ ] SSL certificate valid

### Emails Not Working

- [ ] Integration configured
- [ ] API keys correct
- [ ] List/audience selected
- [ ] SMTP configured (recommended)
- [ ] SPF/DKIM records set
- [ ] Test email succeeds