Troubleshooting & Debugging Guide

This guide consolidates common issues, diagnostic steps, and detailed debugging instructions for admins and developers running ShahiAssist.

—

Table of Contents

1. Quick Troubleshooting Checklist
2. Logging & Debug Mode
3. Common Issues (and fixes)

– Plugin activation problems
– Tickets not saving
– Emails not sending
– KB article 404s
– JS/CSS conflicts
– REST API errors
– Webhook failures

4. Database & Data Integrity
5. Performance Troubleshooting
6. Revert/Recovery Steps
7. When to Contact Support

—

1. Quick Troubleshooting Checklist


• Verify plugin is activated
• Ensure system requirements (PHP 8.0+, WP 6.0+)
• Flush permalinks (Settings → Permalinks → Save)
• Verify file/folder permissions (wp-content/uploads writable)
• Check wp-content/debug.log for PHP errors
• Test email delivery with a known-good SMTP tool
• Disable caching temporarily for admin flows

2. Logging & Debug Mode


Enable WP debug mode in wp-config.php when investigating issues:

`php
define(‘WP_DEBUG’, true);
define(‘WPDEBUGLOG’, true);
define(‘WPDEBUGDISPLAY’, false);
`

• After reproducing the issue, check wp-content/debug.log for fatal errors or warnings.
• ShahiAssist also writes action-specific logs when Settings → Advanced → Debug Mode is enabled. Logs are stored in wp-content/uploads/shahi-assist/logs/.
• For webhook delivery debugging: enable Integrations → Webhooks → Debug Mode to capture payloads and responses.

3. Common Issues (and fixes)


Plugin Won’t Activate / White Screen


• Symptoms: Blank page or HTTP 500 on activation
• Steps:

1. Check wp-content/debug.log for fatal errors (missing function, class or PHP syntax error)
2. Verify PHP version >= 8.0
3. Increase memory limit in wp-config.php:
`php
define(‘WPMEMORYLIMIT’, ‘256M’);
`
4. Ensure required PHP extensions installed (mbstring, json, curl)

Tickets Not Saving


• Symptoms: Submit form returns error or reloads without creating ticket
• Steps:

1. Check browser console for JS errors (could block AJAX)
2. Check server phperrorlog for warnings
3. Verify wp-content/uploads permissions
4. Confirm nonce verification: if failing, you might see 403 responses for admin-ajax
5. Test creating a ticket via Admin → Tickets → Add New — if that works, the problem is frontend submission (JS/AJAX)

Email Notifications Not Sending


• Symptoms: No confirmation emails, agent notifications missing
• Steps:

1. Check ShahiAssist → Settings → Emails for From address correctness
2. Use WP Mail SMTP plugin to test mail delivery and view logs
3. Check spam folder or email provider suppression lists
4. Check server mail logs or consult host if using PHP mail()
5. Test with wp_mail() directly in a small snippet to isolate plugin vs server issue

KB Article 404s / Permalink Issues


• Symptoms: Visiting KB archive or article returns 404
• Fix:

– Go to Settings → Permalinks and click Save Changes to flush rewrite rules
– Confirm sakbarticle is registered; if a custom rewrite slug changed, update settings or regenerate permalinks

JavaScript / CSS Conflicts


• Symptoms: UI broken or components not interactive
• Steps:

1. Open browser devtools (Console/Network)
2. Look for Uncaught JS errors: often a conflict with theme or another plugin
3. Temporarily switch to a default WP theme (Twenty Twenty-Four) and test
4. Deactivate other plugins in staging to find conflict
5. For CSS issues, inspect elements and target .sa- classes in overriding stylesheet

REST API Errors (401 / 403 / 404)


• Authentication 401:

– Use Application Passwords or cookie authentication
– Verify the user has the correct capability to access endpoint

• 403 Forbidden on nonce-protected endpoints:

– Ensure requests include valid nonce or proper auth

• 404 Not Found:

– Flush permalinks
– Confirm REST namespace shahi-assist/v1 exists (check wp-json root)

Webhook Failures


• Symptoms: Third-party service not receiving events
• Steps:

1. Confirm webhook URL is reachable (no firewall/blocked IP)
2. Enable webhook debug in Settings → Integrations and inspect logs
3. Check response code from remote server; 2xx is success
4. If remote server returns 4xx/5xx, inspect their logs for cause

4. Database & Data Integrity


Table Locations


• Core data stored in WP posts (wpposts, saticket, sakbarticle) and postmeta (wp_postmeta)
• Taxonomies in wptermtaxonomy, wp_terms

Data Repair


• If ticket metadata is corrupted, use Export/Import to export valid data and re-import
• Use the tools/repair-db.php helper (if packaged) in a dev environment to scan and validate postmeta

Backups


• Always backup DB before running bulk operations
• Export tickets via ShahiAssist → Export/Import

5. Performance Troubleshooting


Slow Queries


• Enable query monitor (Query Monitor plugin) to identify slow DB queries
• Index heavy meta keys used in frequent queries or modify plugin filters to reduce meta lookups

Caching


• Avoid caching dynamic endpoints: exclude admin-ajax.php and API endpoints from cache
• Use object caching (Redis/Memcached) for high-traffic sites

Large Ticket Volumes


• Archive old tickets to a separate table if volume is very large (>100k)
• Use pagination and lazy-loading for large lists

6. Revert / Recovery Steps


Restore from Export


• Use ShahiAssist → Export/Import to import tickets and KB content into a clean instance

Reinstall Plugin


• Deactivate → Delete → Reinstall (ensure you have export backups). Note: settings may be lost if uninstall delete toggle enabled

Rolling Back a Release


• Keep previous ZIPs locally; deactivate current plugin and upload previous version ZIP
• Test on staging before applying to production

7. When to Contact Support


Provide the following when opening a ticket to support team:

• WordPress & PHP versions
• Active theme and plugins list
• Exact steps to reproduce
• Screenshots and console logs
• wp-content/debug.log contents (if enabled)

Contact: shahiassist@gec5.com

—

If you want, I can add a set of troubleshooting scripts (WP-CLI commands) or a debug snippet to drop into mu-plugins/ to collect environment info automatically. Want that?