docs: Add comprehensive troubleshooting guide
📝 Created TROUBLESHOOTING.md: - Quick diagnosis steps - Common issues with solutions - Verification procedures - Emergency rollback guide - Help gathering checklist - Prevention tips 🎯 Covers All Issues: 1. Blank page in WP-Admin - Files not found (404) - Wrong extraction path - Dev mode enabled 2. API 500 errors (namespace) 3. WordPress media not loading 4. Changes not reflecting (caches) 5. File permissions ✅ Step-by-Step Solutions: - Clear instructions - Copy-paste commands - Expected outputs - Verification steps 🚀 Quick Reference: - Installation checker usage - Cache clearing commands - File structure verification - API/asset testing - Error log locations
This commit is contained in:
dwindown
340
TROUBLESHOOTING.md
Normal file
340
TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:
|
||||
```php
|
||||
// Remove this line:
|
||||
define('WOONOOW_ADMIN_DEV', true);
|
||||
|
||||
// Or set to false:
|
||||
define('WOONOOW_ADMIN_DEV', false);
|
||||
```
|
||||
|
||||
Then clear caches:
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
curl -I https://yoursite.com/wp-json/woonoow/v1/store/settings
|
||||
|
||||
# Should return:
|
||||
# HTTP/2 200 OK
|
||||
```
|
||||
|
||||
### 3. Test Assets
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
php -r "opcache_reset();"
|
||||
wp cache flush
|
||||
```
|
||||
|
||||
2. **Verify files after extraction:**
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user