Coming Soon - The Watchman Tower WordPress plugin is currently in development. This documentation is prepared in advance for the upcoming release.

​
Heartbeat Issues

​
Heartbeats Not Sending

Symptoms:
  • “Last heartbeat” timestamp not updating
  • Dashboard shows “Unknown” status
  • No data appearing in Watchman Tower dashboard
Quick fix:
  1. Open Watchman Tower plugin dashboard
  2. Check if status shows yellow “Paused” badge
  3. Toggle “Pause Monitoring” switch to OFF
  4. Send a manual heartbeat to verify
✅ Status should change to green “Connected”
Test WP-Cron:Use WP-CLI to check if the heartbeat event is scheduled. You should see the heartbeat event listed with its schedule time and interval (typically 300 seconds).Not listed? Re-activate the plugin through WP-CLI or the WordPress admin dashboard.WP-Cron disabled? Check your wp-config.php file for the DISABLE_WP_CRON constant. If it’s set to true, you’ll need to set up a system cron job that runs every 5 minutes to trigger WordPress cron tasks.
Test API reachability:Test from your server if you can reach the Watchman Tower API health endpoint at api.watchmantower.com/public/v1/health. You should receive a successful response with status “ok”.Connection refused or timeout?
  • Firewall is blocking outbound HTTPS
  • Contact hosting provider to whitelist api.watchmantower.com
  • Check server’s firewall rules
Via WordPress: You can also test using WordPress’s remote GET function to check connectivity. Review your debug log for the response.
Check browser console:
  1. Open plugin dashboard in WordPress admin
  2. Press F12 to open Developer Tools
  3. Go to Console tab
  4. Look for errors related to wthb or heartbeat
Check if script loaded:
  1. Go to Sources/Debugger tab
  2. Search for heartbeat.js
  3. Should be under wp-content/plugins/watchman-tower/assets/js/
Script not loading?
  • Clear WordPress cache
  • Hard refresh (Ctrl+Shift+R)
  • Check if jQuery is loaded
  • Temporarily disable other plugins to test for conflicts
Activate WordPress debugging:Enable WordPress debug mode by adding debug constants to your wp-config.php file. Set WP_DEBUG and WP_DEBUG_LOG to true, and WP_DEBUG_DISPLAY to false to log errors without displaying them on the site.Watch logs in real-time using your server’s terminal to monitor the debug.log file and filter for heartbeat-related messages.Send a manual heartbeat and watch for errors in the log.Common errors:
  • cURL error 28: Timeout → Network/firewall issue
  • HTTP 401 Unauthorized → Invalid API key
  • HTTP 429 Too Many Requests → Rate limited
  • Fatal error: Memory exhausted → Increase PHP memory

​
Heartbeats Failing with Errors

Symptoms:
  • Heartbeats send but return error messages
  • Dashboard shows specific error (timeout, auth failed, etc.)
Error: HTTP 401 Unauthorized or Authentication failedCauses:
  • Invalid or expired API key
  • Site disconnected from Watchman Tower dashboard
  • Token mismatch
Solutions:
  1. Reconnect site:
    • Go to plugin dashboard
    • Click “Disconnect” (if connected)
    • Go through setup process again with fresh token
  2. Verify API key in database: Use WP-CLI to check if your API key is stored. It should return a long alphanumeric string. If empty, you’ll need to reconnect.
  3. Check Watchman Tower dashboard:
    • Verify site still exists in your sites list
    • Check if site shows “Disconnected” status
    • Try deleting and re-adding if needed
Error: Connection timeout after 30 seconds or cURL error 28Causes:
  • Slow server response
  • Network congestion
  • DNS resolution issues
  • Server firewall
Solutions:
  1. Test DNS resolution: Use command line tools to verify that api.watchmantower.com resolves to a valid IP address. If not, check your DNS settings.
  2. Increase timeout: Add a timeout constant to your wp-config.php file to increase it to 60 seconds or more.
  3. Check server load: Monitor your server’s CPU and memory usage. High load can delay API requests. Consider upgrading hosting if consistently overloaded.
  4. Test direct connection: Measure how long it takes to connect to the Watchman Tower API. If it takes more than 5 seconds, your network path may be slow.
Error: HTTP 429 Too Many Requests or Rate limit exceededCauses:
  • Too many heartbeats in short time
  • Multiple sites from same IP
  • Manual heartbeat button spammed
Solutions:
  1. Increase heartbeat interval:
    • Open plugin settings
    • Set interval to 300s or higher
    • Wait for cooldown period (usually 5-10 minutes)
  2. Check for duplicate cron jobs: List your WordPress cron events to ensure there’s only ONE heartbeat event scheduled. If you see multiple events, delete them all and reactivate the plugin to start fresh.
  3. Contact support if issue persists - may need rate limit adjustment
Error: HTTP 500 Internal Server Error or 502 Bad GatewayCauses:
  • Watchman Tower API temporary outage
  • Maintenance window
  • Server overload
Solutions:
  1. Check status page: https://status.watchmantower.com
  2. Wait and retry:
    • Plugin automatically retries on next cycle
    • Exponential backoff prevents spam
    • Usually resolves within 5-10 minutes
  3. If persistent (>1 hour):
    • Contact Watchman Tower support
    • Check community forum for announcements
    • Monitor social media for updates

​
Connection Issues

​
Can’t Connect to Watchman Tower

Symptoms:
  • Entered token but connection fails
  • “Invalid token” error message
Solutions:
  1. Verify token is correct:
    • Token format: alphanumeric, ~50-100 characters
    • Check for extra spaces (copy-paste issue)
    • Token is case-sensitive
  2. Get fresh token:
    • Tokens expire after 24 hours if unused
    • Generate new one from Watchman Tower dashboard
    • Use immediately after generation
  3. Check token status:
    • In Watchman Tower dashboard, go to Sites
    • Find the pending registration token
    • If expired, delete and create new one
Symptoms:
  • Entered email/password but account creation fails
  • Email already exists error
Solutions:
  1. Email already registered:
    • Use “Connect with existing account” instead
    • Or use password reset to access existing account
    • Then get register token from dashboard
  2. Validation errors:
    • Email must be valid format
    • Password minimum 8 characters
    • Check for JavaScript errors in console
  3. SMTP/Email issues:
    • Verification email may take 5-10 minutes
    • Check spam folder
    • Ensure your WordPress can send emails by testing with WP-CLI
Symptoms:
  • Was connected, now shows “Disconnected”
  • 401 errors in debug log
Causes:
  • Site deleted from Watchman Tower dashboard
  • API key revoked
  • Account suspended
  • Database corruption
Solutions:
  1. Check Watchman Tower dashboard:
    • Does site still appear in list?
    • If not, manually deleted - reconnect needed
  2. Verify database options: Check if your site ID, instance ID, and API key are stored in the WordPress database. All three should return values. If any are empty, clean up the plugin data and reconnect by deactivating and reactivating the plugin.
  3. Contact support if account suspended

​
Dashboard Issues

​
Dashboard Not Loading

Causes:
  • PHP fatal error
  • Memory exhaustion
  • JavaScript error
Solutions:
  1. Check error logs: Review the last 50 lines of your WordPress debug.log file or Apache/Nginx error logs to identify the issue.
  2. Increase PHP memory: Add memory limit constants to your wp-config.php file. Set WP_MEMORY_LIMIT to 256M and WP_MAX_MEMORY_LIMIT to 512M.
  3. Disable all other plugins temporarily: Deactivate all plugins except Watchman Tower using WP-CLI. Check if dashboard loads now. If yes, reactivate one by one to find the conflict.
Symptoms:
  • Last heartbeat time frozen
  • Uptime percentage not changing
  • Manual heartbeat button does nothing
Causes:
  • AJAX requests blocked
  • JavaScript errors
  • Cache interference
Solutions:
  1. Check browser console for errors:
    • Press F12 → Console tab
    • Look for red error messages
    • Common: ajaxurl is not defined or wthbData is undefined
  2. Clear all caches:
    • Browser cache (Ctrl+Shift+Delete)
    • WordPress cache (WP Super Cache, W3 Total Cache, etc.)
    • Server cache (Redis, Memcached, Varnish)
    • CDN cache (Cloudflare, etc.)
  3. Test AJAX manually: In your browser console on the plugin dashboard page, you can manually test the AJAX request to get site status. It should return site data. If you get an error, check nonce validity.
  4. Disable security plugins temporarily:
    • Some security plugins block AJAX
    • Wordfence, Sucuri, iThemes Security
    • Whitelist WTHB AJAX actions if needed
Symptoms:
  • Change interval, but reverts on refresh
  • Pause toggle doesn’t stay
Causes:
  • AJAX save failed
  • Database write issue
  • Permissions problem
Solutions:
  1. Check browser Network tab:
    • F12 → Network tab
    • Change setting
    • Look for POST request to admin-ajax.php
    • Check response: should be success message
  2. Test database writes: Test if WordPress can write to the database by creating and deleting a test option using WP-CLI. If this fails, check your database connection and permissions.
  3. Check file permissions: List the plugin directory files and permissions. They should be readable by the web server user (www-data, apache, nginx).

​
Data & Metrics Issues

​
Incorrect Uptime Percentage

Causes:
  • Recent connection/disconnection
  • Calculation period (30 days)
  • Server timezone mismatch
  • Data sync delay
Solutions:
  1. Wait for more data: Needs at least 24 hours of heartbeats for accurate calculation
  2. Check server timezone: Verify your WordPress timezone setting matches your actual timezone. Update it in Settings → General if needed.
  3. Verify in Watchman Tower dashboard: Plugin shows cached data; web dashboard is source of truth

​
Missing Metrics in Watchman Tower

Symptoms:
  • Some data fields empty in dashboard
  • Incomplete plugin list
  • PHP version showing “Unknown”
Causes:
  • Permissions restrictions
  • Server security settings
  • PHP functions disabled
  • Incomplete heartbeat payload
Solutions:
  1. Check PHP functions: Access your server’s phpinfo to see which PHP functions are available. Look for disabled functions like disk_free_space, disk_total_space, or memory_get_usage.
  2. Enable required functions: In your php.ini file, check the disable_functions directive. Ensure that disk_free_space, disk_total_space, and memory_get_usage are NOT listed as disabled.
  3. Test metrics collection: Use WP-CLI to evaluate the metrics collection function and check which fields are missing from the output.

​
Performance Issues

​
Plugin Slowing Down Site

Symptoms:
  • Slow admin dashboard
  • High server load
  • Memory warnings
Solutions:
1

Increase Heartbeat Interval

Set to 600-900 seconds for less frequent checks
2

Optimize WordPress

  • Update PHP to 8.0+
  • Enable opcode caching (OPcache)
  • Use object caching (Redis/Memcached)
3

Check for Conflicts

Test with only Watchman Tower active using WP-CLI by deactivating all other plugins. If the site is fast now, reactivate plugins one by one to find the culprit.
4

Monitor Plugin Performance

Use Query Monitor plugin to see:
  • Database queries
  • HTTP requests
  • Memory usage
  • PHP errors

​
Multisite Issues

​
Plugin Not Working on Subsites

Causes:
  • Network-activated but not configured per-site
  • Subsite lacks admin permissions
  • Database prefix issues
Solutions:
  1. Configure per-subsite:
    • Switch to subsite
    • Go to Watchman Tower dashboard
    • Connect site individually (each gets own instance ID)
  2. Check network settings: Use WP-CLI to list all multisite installations and check the plugin status for each subsite.
  3. Network admin controls:
    • Super admins can view all subsite connections
    • Each subsite has independent monitoring
    • Can’t share single token across network

​
Still Having Issues?

Check Documentation

Review full WordPress agent docs

Enable Debug Mode

Add debug constants to wp-config.php to enable logging and troubleshooting

Contact Support

Submit ticket with debug logs

Community Forum

Ask the community

​
Diagnostic Checklist

Before contacting support, gather this information:
  • WordPress version (check via WP-CLI or admin dashboard)
  • PHP version (check via command line)
  • Plugin version (check in plugins list)
  • Hosting provider and plan
  • Error messages from debug.log
  • Browser console errors (screenshot)
  • Heartbeat interval setting
  • Last successful heartbeat timestamp
  • Can server reach api.watchmantower.com?
  • List of active plugins
  • Active theme name
Generate diagnostic report: Use WP-CLI to create a comprehensive diagnostic report and attach this when contacting support for faster resolution.