WooNooW/TROUBLESHOOTING.md

Troubleshooting Guide

Quick Diagnosis

Step 1: Run Installation Checker

Upload check-installation.php to your server and visit:

https://yoursite.com/wp-content/plugins/woonoow/check-installation.php

This will show you exactly what's wrong.

---

Common Issues

Issue 1: Blank Page in WP-Admin

Symptoms:

• Blank white page when visiting /wp-admin/admin.php?page=woonoow
• Or shows "Please Configure Marketing Setup first"
• No SPA loads

Diagnosis:

1. Open browser console (F12)
2. Check Network tab
3. Look for app.js and app.css

Possible Causes & Solutions:

A. Files Not Found (404)

❌ admin-spa/dist/app.js → 404 Not Found
❌ admin-spa/dist/app.css → 404 Not Found

Solution:

# The dist files are missing!
# Re-extract the zip file:
cd /path/to/wp-content/plugins
rm -rf woonoow
unzip woonoow.zip

# Verify files exist:
ls -la woonoow/admin-spa/dist/
# Should show: app.js (2.4MB) and app.css (70KB)

B. Wrong Extraction Path

If you extracted into plugins/woonoow/woonoow/, the paths will be wrong.

Solution:

# Correct structure:
wp-content/plugins/woonoow/woonoow.php ✓
wp-content/plugins/woonoow/admin-spa/dist/app.js ✓

# Wrong structure:
wp-content/plugins/woonoow/woonoow/woonoow.php ✗
wp-content/plugins/woonoow/woonoow/admin-spa/dist/app.js ✗

# Fix:
cd /path/to/wp-content/plugins
rm -rf woonoow
unzip woonoow.zip
# This creates: plugins/woonoow/ (correct!)

C. Dev Mode Enabled

❌ Trying to load from localhost:5173

Solution: Edit wp-config.php and remove or set to false:

// Remove this line:
define('WOONOOW_ADMIN_DEV', true);

// Or set to false:
define('WOONOOW_ADMIN_DEV', false);

Then clear caches:

php -r "opcache_reset();"
wp cache flush

---

Issue 2: API 500 Errors

Symptoms:

• All API endpoints return 500
• Console shows: "Internal Server Error"
• Error log: Class "WooNooWAPIPaymentsController" not found

Cause: Namespace case mismatch (old code)

Solution:

# Check if you have the fix:
grep "use WooNooW" includes/Api/Routes.php

# Should show (lowercase 'i'):
# use WooNooW\Api\PaymentsController;

# If it shows (uppercase 'I'):
# use WooNooW\API\PaymentsController;
# Then you need to update!

# Update:
git pull origin main
# Or re-upload the latest zip

# Clear caches:
php -r "opcache_reset();"
wp cache flush

---

Issue 3: WordPress Media Not Loading (Standalone)

Symptoms:

• Error: "WordPress Media library is not loaded"
• "Choose from Media Library" button doesn't work
• Only in standalone mode (/admin)

Cause: Missing wp.media scripts

Solution: Already fixed in latest code. Update:

git pull origin main
# Or re-upload the latest zip

php -r "opcache_reset();"

---

Issue 4: Changes Not Reflecting

Symptoms:

• Uploaded new code but still seeing old errors
• Fixed files but issues persist

Cause: Multiple cache layers

Solution:

# 1. Clear PHP OPcache (MOST IMPORTANT!)
php -r "opcache_reset();"

# Or visit:
# https://yoursite.com/wp-content/plugins/woonoow/check-installation.php?action=clear_opcache

# 2. Clear WordPress object cache
wp cache flush

# 3. Restart PHP-FPM (if above doesn't work)
sudo systemctl restart php8.1-fpm
# or
sudo systemctl restart php-fpm

# 4. Clear browser cache
# Hard refresh: Ctrl+Shift+R (Windows/Linux)
# Hard refresh: Cmd+Shift+R (Mac)

---

Issue 5: File Permissions

Symptoms:

• 403 Forbidden errors
• Can't access files

Solution:

cd /path/to/wp-content/plugins/woonoow

# Set correct permissions:
find . -type f -exec chmod 644 {} \;
find . -type d -exec chmod 755 {} \;

# Verify:
ls -la admin-spa/dist/
# Should show: -rw-r--r-- (644) for files

---

Verification Steps

After fixing, verify everything works:

1. Check Files

cd /path/to/wp-content/plugins/woonoow

# These files MUST exist:
ls -lh woonoow.php                    # Main plugin file
ls -lh includes/Admin/Assets.php      # Assets handler
ls -lh includes/Api/Routes.php        # API routes
ls -lh admin-spa/dist/app.js          # SPA JS (2.4MB)
ls -lh admin-spa/dist/app.css         # SPA CSS (70KB)

2. Test API

curl -I https://yoursite.com/wp-json/woonoow/v1/store/settings

# Should return:
# HTTP/2 200 OK

3. Test Assets

curl -I https://yoursite.com/wp-content/plugins/woonoow/admin-spa/dist/app.js

# Should return:
# HTTP/2 200 OK
# Content-Length: 2489867

4. Test WP-Admin

Visit: https://yoursite.com/wp-admin/admin.php?page=woonoow

Should see:

• ✓ WooNooW dashboard loads
• ✓ No console errors
• ✓ Navigation works

Should NOT see:

• ✗ Blank page
• ✗ "Please Configure Marketing Setup"
• ✗ Errors about localhost:5173

5. Test Standalone

Visit: https://yoursite.com/admin

Should see:

• ✓ Standalone admin loads
• ✓ Login page (if not logged in)
• ✓ Dashboard (if logged in)

---

Emergency Rollback

If everything breaks:

# 1. Deactivate plugin
wp plugin deactivate woonoow

# 2. Remove plugin
rm -rf /path/to/wp-content/plugins/woonoow

# 3. Re-upload fresh zip
unzip woonoow.zip -d /path/to/wp-content/plugins/

# 4. Reactivate
wp plugin activate woonoow

# 5. Clear all caches
php -r "opcache_reset();"
wp cache flush

---

Getting Help

If issues persist, gather this info:

1. Run installation checker:

   https://yoursite.com/wp-content/plugins/woonoow/check-installation.php
   

   Take screenshot of results

2. Check error logs:

   tail -50 /path/to/wp-content/debug.log
   tail -50 /var/log/php-fpm/error.log
   

3. Browser console:

   • Open DevTools (F12)
   • Go to Console tab
   • Take screenshot of errors

4. Network tab:

   • Open DevTools (F12)
   • Go to Network tab
   • Reload page
   • Take screenshot showing failed requests

5. File structure:

   ls -la /path/to/wp-content/plugins/woonoow/
   ls -la /path/to/wp-content/plugins/woonoow/admin-spa/dist/
   

Send all this info when requesting help.

---

Prevention

To avoid issues in the future:

1. Always clear caches after updates:

   php -r "opcache_reset();"
   wp cache flush
   

2. Verify files after extraction:

   ls -lh admin-spa/dist/app.js
   # Should be ~2.4MB
   

3. Use installation checker: Run it after every deployment

4. Keep backups: Before updating, backup the working version

5. Test in staging first: Don't deploy directly to production