=== Badwolf Web IRC Client - Troubleshooting Guide ===


Version: 5.2.0
Last Updated: January 18, 2026


=== Table of Contents ===

1. Connection Issues
2. WordPress 6.9 Specific Issues
3. SSL/TLS Certificate Problems
4. WebSocket Errors
5. Plugin Not Loading
6. Performance Issues
7. Browser Compatibility
8. UnrealIRCd Server Issues
9. Common Error Messages
10. Debugging Tools and Techniques


================================================================================
1. CONNECTION ISSUES
================================================================================


--- Problem: "Reconnecting..." Message Appears Constantly ---


Symptoms:
• Status shows "Reconnecting in Xs... (attempt Y)"
• Never successfully connects
• WebSocket closes immediately after opening


Solutions:


A. Check UnrealIRCd is Running


   ps aux | grep unrealircd


   If not running:
   cd /home/unrealircd/unrealircd
   ./unrealircd start


B. Verify Port is Listening


   sudo netstat -tlnp | grep 7443


   Should show:
   tcp  0  0  0.0.0.0:7443  0.0.0.0:*  LISTEN  [PID]/unrealircd


C. Check Firewall


   sudo ufw status


   Ensure port 7443 is allowed:
   sudo ufw allow 7443/tcp


D. Test WebSocket Connection


   Use: https://www.piesocket.com/websocket-tester
   URL: wss://irc.yourdomain.com:7443


   If fails, problem is server-side, not plugin.


E. Check UnrealIRCd Logs


   tail -50 /home/unrealircd/unrealircd/logs/ircd.log


   Look for errors related to WebSocket or TLS.


--- Problem: Connects Then Immediately Disconnects ---


Symptoms:
• Shows "Connected" briefly
• Then "Disconnected"
• Error code 1006 in browser console


Solutions:


A. Check Browser Console for Errors


   Press F12 → Console tab
   Look for: "data.trim is not a function"


   Solution: Update to plugin version 5.2.0 which fixes this.


B. Verify WebSocket Configuration


   In unrealircd.conf, ensure:


   listen {
       ip *;
       port 7443;
       options {
           tls;
           websocket;  # Not websocket { type text; }
       }
   }


C. Check SSL Certificate


   cd /home/unrealircd/unrealircd
   ./unrealircd restart


   Look for certificate warnings in output.


--- Problem: "Connection Failed" Error ---


Symptoms:
• Never gets past "Connecting..."
• Browser console shows connection refused


Solutions:


A. Verify WebSocket URL is Correct


   WordPress Admin → Settings → Badwolf Web IRC Client
   Check: wss://irc.yourdomain.com:7443


   Common mistakes:
• Using http:// instead of wss://
• Wrong port number
• Typo in domain name


B. Check DNS Resolution


   nslookup irc.yourdomain.com


   Should return your server's IP address.


C. Test Direct Connection


   telnet irc.yourdomain.com 7443


   Should connect (then show garbled text).
   If "Connection refused", port is not open.


================================================================================
2. WORDPRESS 6.9 SPECIFIC ISSUES
================================================================================


--- Problem: Plugin Stopped Working After WordPress 6.9 Update ---


Symptoms:
• IRC client interface doesn't appear
• JavaScript not loading
• Blank space where client should be


Solutions:


A. Update to Plugin Version 5.2.0


   This version includes WordPress 6.9 compatibility fixes.


   Download from:
• WordPress.org plugin repository
• GitHub: https://github.com/badwolf1972/web-irc-client


B. Clear All Caches

1. WordPress cache (if using caching plugin)
2. Browser cache (Ctrl+Shift+R or Cmd+Shift+R)
3. Server cache (if using Varnish, Redis, etc.)


C. Verify Shortcode is Correct


   [web_irc_client]


   Not: [web-irc-client] or [webircclient]


D. Check for JavaScript Errors


   Press F12 → Console tab
   Look for errors related to web-irc.js


--- Problem: Configuration Not Being Passed to JavaScript ---


Symptoms:
• Client loads but shows "Not configured"
• WebSocket URL shows "Not set"
• Channel shows "None"


Solutions:


A. Verify Settings are Saved


   WordPress Admin → Settings → Badwolf Web IRC Client
   Click "Save Changes" even if no changes made.


B. Check Browser Console


   Press F12 → Console
   Type: WEB_IRC_CLIENT_CFG


   Should show your configuration object.
   If undefined, plugin not loading correctly.


C. Deactivate and Reactivate Plugin


   WordPress Admin → Plugins
   Deactivate "Badwolf Web IRC Client"
   Activate it again


================================================================================
3. SSL/TLS CERTIFICATE PROBLEMS
================================================================================


--- Problem: Certificate Expired ---


Symptoms:
• UnrealIRCd logs show: "certificate expired"
• WebSocket connection fails with SSL error
• Browser shows security warning


Solutions:


A. Check Certificate Expiry


   sudo certbot certificates


   Look at "Expiry Date" for irc.yourdomain.com


B. Renew Certificate


   sudo certbot renew --force-renewal


C. Copy to UnrealIRCd


   sudo cp /etc/letsencrypt/live/irc.yourdomain.com/fullchain.pem /home/unrealircd/unrealircd/conf/tls/
   sudo cp /etc/letsencrypt/live/irc.yourdomain.com/privkey.pem /home/unrealircd/unrealircd/conf/tls/
   sudo chown unrealircd:unrealircd /home/unrealircd/unrealircd/conf/tls/*.pem
   sudo chmod 600 /home/unrealircd/unrealircd/conf/tls/privkey.pem
   sudo chmod 644 /home/unrealircd/unrealircd/conf/tls/fullchain.pem


D. Restart UnrealIRCd


   cd /home/unrealircd/unrealircd
   ./unrealircd restart


--- Problem: Certificate Not Trusted ---


Symptoms:
• Browser shows "NET::ERR_CERT_AUTHORITY_INVALID"
• Self-signed certificate warning


Solutions:


A. Use Let's Encrypt Certificate


   Self-signed certificates are not trusted by browsers.
   Get a free Let's Encrypt certificate:


   sudo certbot certonly --standalone -d irc.yourdomain.com


B. Verify Certificate Chain


   openssl s_client -connect irc.yourdomain.com:7443 -showcerts


   Should show complete certificate chain.


--- Problem: Wrong Certificate Being Used ---


Symptoms:
• Certificate is for different domain
• Certificate is valid but connection fails


Solutions:


A. Check Certificate Paths in UnrealIRCd Config


   nano /home/unrealircd/unrealircd/conf/unrealircd.conf


   Verify paths in tls-options block:
   certificate "/home/unrealircd/unrealircd/conf/tls/fullchain.pem";
   key "/home/unrealircd/unrealircd/conf/tls/privkey.pem";


B. Verify Certificate Files


   ls -la /home/unrealircd/unrealircd/conf/tls/


   Check file dates and sizes.


C. Test Certificate


   openssl x509 -in /home/unrealircd/unrealircd/conf/tls/fullchain.pem -text -noout


   Check "Subject" and "Issuer" fields.


================================================================================
4. WEBSOCKET ERRORS
================================================================================


--- Error Code 1006: Abnormal Closure ---


Causes:
• Server closed connection unexpectedly
• SSL/TLS handshake failed
• Binary data handling issue


Solutions:


A. Update to Plugin Version 5.2.0


   Includes fix for binary WebSocket data handling.


B. Check UnrealIRCd Logs


   tail -f /home/unrealircd/unrealircd/logs/ircd.log


   Look for errors when connection attempts occur.


C. Verify WebSocket Module is Loaded


   In unrealircd.conf:
   loadmodule "websocket";


D. Check Browser Console


   Look for: "data.trim is not a function"
   This indicates binary data issue (fixed in 5.2.0)


--- Error Code 1000: Normal Closure ---


This is normal when:
• User closes browser tab
• User navigates away from page
• Intentional disconnect


No action needed.


--- Error Code 1001: Going Away ---


Causes:
• Server is shutting down
• Server is restarting


Solutions:


A. Check if UnrealIRCd is Running


   ps aux | grep unrealircd


B. Check Server Logs


   tail -50 /home/unrealircd/unrealircd/logs/ircd.log


--- Error: "WebSocket connection failed" ---


Causes:
• Port blocked by firewall
• DNS not resolving
• Server not listening


Solutions:


A. Test Port Accessibility


   telnet irc.yourdomain.com 7443


   Should connect.


B. Check Firewall


   sudo ufw status
   sudo iptables -L -n | grep 7443


C. Verify DNS


   nslookup irc.yourdomain.com
   ping irc.yourdomain.com


================================================================================
5. PLUGIN NOT LOADING
================================================================================


--- Problem: IRC Client Interface Not Appearing ---


Symptoms:
• Shortcode shows as plain text
• Blank space where client should be
• No HTML output


Solutions:


A. Verify Plugin is Activated


   WordPress Admin → Plugins
   "Badwolf Web IRC Client" should show "Deactivate" link.


B. Check Shortcode Syntax


   Correct: [web_irc_client]
   Wrong: [web-irc-client] or [webircclient]


C. Clear WordPress Cache


   If using caching plugin (WP Super Cache, W3 Total Cache, etc.):
• Clear cache
• Purge all caches


D. Check for Plugin Conflicts


   Deactivate other plugins one by one to identify conflicts.


E. Check PHP Error Log


   Look for PHP errors:
   tail -50 /var/log/apache2/error.log

or

   tail -50 /var/log/nginx/error.log


--- Problem: JavaScript Not Loading ---


Symptoms:
• HTML appears but no functionality
• Browser console shows 404 for web-irc.js


Solutions:


A. Verify File Exists


   ls -la /var/www/html/wp-content/plugins/badwolf-web-irc-client/assets/web-irc.js


B. Check File Permissions


   chmod 644 /var/www/html/wp-content/plugins/badwolf-web-irc-client/assets/web-irc.js


C. Clear Browser Cache


   Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)


D. Check for JavaScript Errors


   Press F12 → Console tab
   Look for loading errors


--- Problem: CSS Not Loading ---


Symptoms:
• Client appears but looks broken
• No styling applied


Solutions:


A. Verify CSS File Exists


   ls -la /var/www/html/wp-content/plugins/badwolf-web-irc-client/assets/web-irc.css


B. Check File Permissions


   chmod 644 /var/www/html/wp-content/plugins/badwolf-web-irc-client/assets/web-irc.css


C. Clear Browser Cache


   Hard refresh: Ctrl+Shift+R


D. Check for CSS Conflicts


   Press F12 → Elements tab
   Inspect IRC client elements
   Look for conflicting styles from theme


================================================================================
6. PERFORMANCE ISSUES
================================================================================


--- Problem: Slow Connection ---


Symptoms:
• Takes long time to connect
• Messages delayed
• Laggy interface


Solutions:


A. Check Server Resources


   top


   Look for high CPU or memory usage.


B. Check Network Latency


   ping irc.yourdomain.com


   Should be < 100ms for good performance.


C. Optimize UnrealIRCd


   In unrealircd.conf:


   set {
       anti-flood {
           # Adjust these values
       }
   }


D. Check Browser Performance


   Press F12 → Performance tab
   Record and analyze


--- Problem: High Memory Usage ---


Symptoms:
• Browser tab uses lots of memory
• Browser becomes slow


Solutions:


A. Limit Message History


   In web-irc.js, adjust:
   messageLimit: 500  // Reduce this number


B. Close Unused Tabs


   Each PM window uses memory.


C. Restart Browser


   Close and reopen browser to clear memory.


================================================================================
7. BROWSER COMPATIBILITY
================================================================================


--- Problem: Not Working in Specific Browser ---


Solutions:


A. Check Browser Version


   Minimum versions:
• Chrome 16+
• Firefox 11+
• Safari 7+
• Edge 12+


B. Enable JavaScript


   Ensure JavaScript is enabled in browser settings.


C. Check for Browser Extensions


   Disable ad blockers and privacy extensions.
   Test in incognito/private mode.


D. Check Console for Errors


   Press F12 → Console
   Look for compatibility errors


--- Problem: Not Working on Mobile ---


Solutions:


A. Test in Mobile Browser


   Use Chrome or Safari on mobile.


B. Check Viewport Settings


   Ensure page is mobile-responsive.


C. Test WebSocket on Mobile


   Use mobile WebSocket testing app.


================================================================================
8. UNREALIRCD SERVER ISSUES
================================================================================


--- Problem: UnrealIRCd Won't Start ---


Solutions:


A. Check Configuration


   cd /home/unrealircd/unrealircd
   ./unrealircd configtest


   Fix any errors shown.


B. Check Logs


   tail -50 /home/unrealircd/unrealircd/logs/ircd.log


C. Check Port Conflicts


   sudo netstat -tlnp | grep 7443


   If another process is using the port, stop it.


D. Check Permissions


   ls -la /home/unrealircd/unrealircd/


   Ensure unrealircd user owns files.


--- Problem: WebSocket Module Not Loading ---


Solutions:


A. Verify Module Exists


   ls -la /home/unrealircd/unrealircd/modules/websocket.so


B. Check Module Load in Config


   grep "loadmodule.*websocket" /home/unrealircd/unrealircd/conf/unrealircd.conf


   Should show: loadmodule "websocket";


C. Recompile UnrealIRCd


   cd /home/unrealircd/unrealircd-source
   ./Config
   make clean
   make
   make install


--- Problem: Users Can't Join Channel ---


Solutions:


A. Check Channel Modes


   /mode #channel


   Remove restrictive modes if needed.


B. Check Ban Lists


   /mode #channel +b


   Remove any bans affecting users.


C. Check Channel Limits


   /mode #channel +l


   Increase limit if needed.


================================================================================
9. COMMON ERROR MESSAGES
================================================================================


--- "Error: No channel configured" ---


Solution:
WordPress Admin → Settings → Badwolf Web IRC Client
Set "Default Channel" field (e.g., #general)


--- "Error: No WebSocket URL configured" ---


Solution:
WordPress Admin → Settings → Badwolf Web IRC Client
Set "WebSocket URL" field (e.g., wss://irc.yourdomain.com:7443)


--- "Connection error" ---


Causes:
• Server not reachable
• Firewall blocking
• DNS not resolving


Solutions: See "Connection Issues" section above.


--- "Max reconnection attempts reached" ---


Causes:
• Server persistently unavailable
• Configuration error


Solutions:
1. Check UnrealIRCd is running
2. Verify WebSocket URL is correct
3. Check firewall rules
4. Refresh page to reset attempts


--- "Invalid nickname" ---


Causes:
• Nickname contains invalid characters
• Nickname too long (>30 characters)


Solutions:
Use only: a-z, A-Z, 0-9, _, -, [, ], \, `, ^, {, }, |


--- "Certificate expired" ---


Solution: See "SSL/TLS Certificate Problems" section above.


================================================================================
10. DEBUGGING TOOLS AND TECHNIQUES
================================================================================


--- Browser Developer Tools ---


Chrome/Firefox/Edge:
Press F12 or Right-click → Inspect


Useful tabs:
• Console: JavaScript errors and logs
• Network: WebSocket connection details
• Elements: HTML structure and CSS


--- WebSocket Testing Tools ---


Online testers:
• https://www.piesocket.com/websocket-tester
• https://www.websocket.org/echo.html


Usage:
1. Enter: wss://irc.yourdomain.com:7443
2. Click Connect
3. Check connection status


--- UnrealIRCd Debugging ---


Enable debug mode:
./unrealircd -d


View real-time logs:
tail -f /home/unrealircd/unrealircd/logs/ircd.log


Test configuration:
./unrealircd configtest


--- Network Debugging ---


Test DNS:
nslookup irc.yourdomain.com
dig irc.yourdomain.com


Test connectivity:
ping irc.yourdomain.com
telnet irc.yourdomain.com 7443


Test SSL:
openssl s_client -connect irc.yourdomain.com:7443


Check ports:
sudo netstat -tlnp | grep 7443
sudo ss -tlnp | grep 7443


--- WordPress Debugging ---


Enable WordPress debug mode:


Edit wp-config.php:
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);


Check debug log:
tail -f /var/www/html/wp-content/debug.log


--- Plugin Debugging ---


Check if plugin is loaded:
WordPress Admin → Plugins
Verify "Badwolf Web IRC Client" is active


Check plugin files:
ls -la /var/www/html/wp-content/plugins/badwolf-web-irc-client/


Check JavaScript console:
Type: WebIRCClient
Should show object with methods


--- Logging Connection Attempts ---


In browser console, watch for:
🔌 Connecting to: wss://...
✅ WebSocket connected
📨 Raw data: ...
📊 Status: Connected


These logs help identify where connection fails.


================================================================================


Still Having Issues?

1. Check GitHub Issues:
https://github.com/badwolf1972/web-irc-client/issues

2. WordPress Support Forum:
https://wordpress.org/support/plugin/badwolf-web-irc-client/

3. UnrealIRCd Support:
irc.unrealircd.org #unreal-support


When asking for help, provide:
• Plugin version
• WordPress version
• PHP version
• UnrealIRCd version
• Browser and version
• Error messages from browser console
• Relevant log entries
• Steps to reproduce the issue
