woonoow-docs/docs/resources/troubleshooting.mdx

---
title: Troubleshooting
description: Common issues and their solutions
date: 2024-01-31
---

## Blank Pages

WooCommerce pages (shop, cart, checkout) show blank content.

<div className="pl-4">
   <Steps>
      <Step title="Check SPA Mode Setting">
         - Go to **WooNooW → Appearance → General**
         - Ensure **SPA Mode** is set to "Full"
         - If you want native WooCommerce, set to "Disabled"
      </Step>
      <Step title="Flush Permalinks">
         - Go to **Settings → Permalinks**
         - Click **Save Changes** (no changes needed)
         - This refreshes rewrite rules
      </Step>
      <Step title="Clear Cache">
         - If using a caching plugin:
         - Clear page cache
         - Clear object cache
         - Purge CDN cache (if applicable)
      </Step>
   </Steps>
</div>

---

## 404 Errors on SPA Routes

Visiting `/store/shop` or `/store/product/...` shows a 404 error.

<div className="pl-4">
   <Steps>
      <Step title="Flush Permalinks">
         - Go to **Settings → Permalinks**
         - Click **Save Changes**
      </Step>
      <Step title="Check Store Page Exists">
         - Go to **Pages**
         - Verify "Store" page exists and is published
         - The page should contain `[woonoow_spa]` shortcode
      </Step>
      <Step title="Check SPA Page Setting">
         - Go to **WooNooW → Appearance → General**
         - Ensure **SPA Page** is set to the Store page
      </Step>
   </Steps>
</div>

---

## Product Images Not Loading

Products show placeholder images instead of actual images.

<div className="pl-4">
   <Steps>
      <Step title="Regenerate Thumbnails">
         - Install "Regenerate Thumbnails" plugin
         - Run regeneration for all images
      </Step>
      <Step title="Check Image URLs">
         - Ensure images have valid URLs
         - Check for mixed content (HTTP vs HTTPS)
      </Step>
   </Steps>
</div>

---

## Slow Performance

SPA feels slow or laggy.

<div className="pl-4">
   <Steps>
      <Step title="Enable Caching">
         - Install a caching plugin (WP Super Cache, W3 Total Cache)
         - Enable object caching (Redis/Memcached)
      </Step>
      <Step title="Optimize Images">
         - Use WebP format
         - Compress images before upload
         - Use lazy loading
      </Step>
      <Step title="Check Server Resources">
         - Upgrade hosting if on shared hosting
         - Consider VPS or managed WordPress hosting
      </Step>
   </Steps>
</div>

---

## Checkout Not Working

Checkout page won't load or payment fails.

<div className="pl-4">
   <Steps>
      <Step title="Check Payment Gateway">
         - Go to **WooCommerce → Settings → Payments**
         - Verify payment method is enabled
         - Check API credentials
      </Step>
      <Step title="Check SSL Certificate">
         - Checkout requires HTTPS
         - Verify SSL is properly installed
      </Step>
      <Step title="Check for JavaScript Errors">
         - Open browser Developer Tools (F12)
         - Check Console for errors
         - Look for blocked scripts
      </Step>
   </Steps>
</div>

---

## Emails Not Sending

Order confirmation emails not being received.

<div className="pl-4">
   <Steps>
      <Step title="Check Email Settings">
         - Go to **WooNooW → Settings → Notifications**
         - Verify email types are enabled
      </Step>
      <Step title="Check WordPress Email">
         - Test with a plugin like "Check & Log Email"
         - Consider using SMTP plugin (WP Mail SMTP)
      </Step>
      <Step title="Check Spam Folder">
         - Emails may be in recipient's spam folder
         - Add sender to whitelist
      </Step>
   </Steps>
</div>

---

## Plugin Conflicts

WooNooW doesn't work after installing another plugin.

<div className="pl-4">
   <Steps>
      <Step title="Steps to Diagnose">
         - Deactivate other plugins one by one
         - Switch to default theme (Twenty Twenty-Three)
         - Check error logs in `wp-content/debug.log`
      </Step>
      <Step title="Check WordPress Email">
         - Test with a plugin like "Check & Log Email"
         - Consider using SMTP plugin (WP Mail SMTP)
      </Step>
      <Step title="Common Conflicting Plugins">
         - Other WooCommerce template overrides
         - Page builder plugins (sometimes)
         - Heavy caching plugins (misconfigured)
      </Step>
   </Steps>
</div>

---

## Getting More Help

If you can't resolve the issue:

<div className="pl-4">
   <Steps>
      <Step title="Collect Information">
         - WordPress version
         - WooCommerce version
         - WooNooW version
         - PHP version
         - Error messages (from debug.log)
      </Step>
      <Step title="Enable Debug Mode">
         - Add to `wp-config.php`:
         ```php
         define('WP_DEBUG', true);
         define('WP_DEBUG_LOG', true);
         ```
      </Step>
      <Step title="Contact Support">
         - Provide the collected information for faster resolution.
      </Step>
   </Steps>
</div>