Troubleshooting

Common issues and their solutions.

Connection Issues

Cannot Connect to Server

Symptoms: Connection times out or fails immediately.

Solutions:

Check server address and port ``` Common ports:
- 6667: Standard IRC
- 6697: SSL/TLS IRC
- 7000: Alternative SSL ```
Verify SSL/TLS settings
- Enable SSL for port 6697
- Disable SSL for port 6667
- Try “Allow Invalid Certs” for self-signed certificates
Check firewall settings
- Ensure outbound connections on IRC ports are allowed
- Try disabling firewall temporarily to test
Test with different server
- Try connecting to irc.libera.chat to verify client works

Connection Drops Frequently

Symptoms: Regular disconnections after successful connection.

Solutions:

Enable Auto-Reconnect
- Settings → Connection → Auto-Reconnect
Adjust Reconnect Delay
- Increase delay to 30-60 seconds
- Prevents rate limiting
Check network stability
- Test internet connection
- Try different network if possible
Disable SSL temporarily
- Test if SSL handshake is causing issues

SASL Authentication Fails

Symptoms: “SASL authentication failed” error.

Solutions:

Verify credentials
- Double-check username and password
- Use app-specific password if required
Check authentication mechanism
- Try PLAIN mechanism
- Some servers require EXTERNAL

Register with NickServ first

/msg NickServ IDENTIFY username password

Wait before joining channels
- Add delay in auto-join commands

Display Issues

Messages Not Appearing

Symptoms: Can send messages but don’t see them or responses.

Solutions:

Check channel focus
- Ensure correct channel is selected
Verify connection status
- Look for green indicator in sidebar
- Reconnect if disconnected
Clear message buffer
```
/clear
```
Check ignore list
- Settings → Privacy → Ignore List

Theme Not Applying

Symptoms: Theme selection doesn’t change appearance.

Solutions:

Restart application
- Close and reopen Patchcord
Clear cache
- Delete theme cache file
- Restart application
Reset settings
- Settings → Advanced → Reset All Settings
Check for updates
- Download latest version

Font Rendering Issues

Symptoms: Text appears blurry or incorrectly sized.

Solutions:

Adjust font settings
- Settings → Appearance → Font Size
- Try 14px or 16px for better readability
Toggle system fonts
- Enable/disable “Use System UI Font”
- Enable/disable “Use System Mono Font”
Check display scaling
- Windows: Settings → Display → Scale
- Try 100% or 125% scaling

Performance Issues

High Memory Usage

Symptoms: Application uses excessive RAM.

Solutions:

Clear message history
- Settings → Advanced → Clear History
Reduce log retention
- Settings → Advanced → Max Log Messages
Limit open channels
- Part unused channels
- Close unused server connections
Disable raw logging
- Settings → Advanced → Raw Log Panel

Slow Response Time

Symptoms: Laggy interface or delayed messages.

Solutions:

Check network latency
```
/ping
```
Reduce visual effects
- Disable animations in settings
- Use simpler theme
Close unused servers
- Disconnect from inactive servers
Update graphics drivers
- Ensure latest GPU drivers installed

Notification Issues

Notifications Not Showing

Symptoms: No desktop notifications on mentions.

Solutions:

Enable notifications
- Settings → Notifications → Enable Notifications
Check system permissions
- Windows: Settings → System → Notifications
- macOS: System Preferences → Notifications
- Linux: Check notification daemon
Configure highlights
- Settings → Notifications → Highlight Keywords
- Add your nickname
Test notification
- Use test button in settings

Tab Flash Not Working

Symptoms: Window doesn’t flash on mentions.

Solutions:

Enable tab flash
- Settings → Notifications → Flash Taskbar
Check window focus
- Tab flash only works when window is inactive
Restart application
- Close and reopen

Desktop App Issues

Application Won’t Start

Symptoms: App crashes on launch or doesn’t open.

Solutions:

Check system requirements
- Windows 10+, macOS 11+, or modern Linux
- 4GB RAM minimum
Reinstall application
- Uninstall completely
- Download fresh installer
- Reinstall
Check for conflicting software
- Antivirus may block
- Add to exceptions list
Run as administrator (Windows)
- Right-click → Run as Administrator

Update Fails

Symptoms: Update download or installation fails.

Solutions:

Manual update
- Download latest from GitHub Releases
- Install manually
Clear update cache
- Delete update folder
- Retry update
Check disk space
- Ensure sufficient free space
- At least 500MB recommended

Platform-Specific Issues

Windows

App blocked by SmartScreen

Solution: Click “More info” → “Run anyway”

Taskbar icon issues

Solution: Right-click taskbar → Taskbar settings → Reset

macOS

“App is damaged” error

Solution:

xattr -cr /Applications/Patchcord.app

Permission denied errors

Solution:

System Preferences → Security & Privacy
Grant Full Disk Access

Linux

Missing dependencies

Solution:

# Ubuntu/Debian
sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev

# Fedora
sudo dnf install gtk3-devel webkit2gtk4.1-devel

AppImage won’t run

Solution:

chmod +x Patchcord.AppImage
./Patchcord.AppImage

System tray icon missing

Solution:

Install libappindicator
Enable extensions for GNOME

Debug Mode

Enable debug logging for troubleshooting:

Open settings
Go to Advanced
Enable “Debug Mode”
Reproduce the issue
Check logs in:
- Windows: %APPDATA%\dev.patchcord.desktop\logs\
- macOS: ~/Library/Logs/dev.patchcord.desktop/
- Linux: ~/.config/dev.patchcord.desktop/logs/

Getting Help

If your issue isn’t listed here:

Check existing issues
- GitHub Issues
Create new issue
- Include OS version
- Patchcord version
- Steps to reproduce
- Screenshots if applicable
Join IRC channel
- #patchcord on Libera.Chat
- Real-time support from community
Email support
- support@patchcord.dev

Previous Steps

Commands - IRC command reference
Configuration - Settings guide
Themes - Theme gallery