Troubleshooting Guide

This guide helps you diagnose and fix common issues with PadRelay.

General Troubleshooting Steps

Before diving into specific issues:

1. Check logs: Review logs in logs/padrelay.log

2. Enable debug mode: Set PADRELAY_DEBUG=1 for detailed logging

3. Verify versions: Ensure client and server use compatible versions

4. Test connectivity: Use ping and telnet to test network

5. Check firewall: Verify firewall allows connections

Connection Issues

Connection Refused

Symptoms:

ERROR: Connection refused to 192.168.1.100:9999

Causes:

• Server not running

• Wrong IP address or port

• Firewall blocking connection

• Server bound to wrong interface

Solutions:

1. Verify server is running:

   # Check if process is running
   ps aux | grep padrelay-server  # Linux/Mac
   tasklist | findstr python      # Windows
   

2. Verify server IP and port:

   netstat -an | grep 9999        # Linux/Mac
   netstat -an | findstr 9999     # Windows
   

3. Test with telnet:

   telnet 192.168.1.100 9999
   

4. Check firewall:

   # Linux
   sudo ufw status
   sudo ufw allow 9999/tcp
   
   # Windows
   # Open Windows Firewall and allow Python or port 9999
   

5. Verify server binding:

   [server]
   host = 0.0.0.0  # Accept connections from all interfaces
   

Connection Timeout

Symptoms:

ERROR: Connection timeout

Solutions:

• Check network connectivity with ping

• Verify no intermediate firewalls blocking

• Try increasing timeout (not currently configurable)

• Check server is responsive (not hung)

Connection Drops

Symptoms:

• Connection established but drops after a few seconds

• Intermittent disconnections

Solutions:

1. Check rate limiting settings (may be too strict)

2. Verify network stability

3. Check heartbeat settings (TCP only)

4. Review logs for errors before disconnect

5. Try using TCP instead of UDP

Authentication Issues

Authentication Failed

Symptoms:

ERROR: Authentication failed

Causes:

• Password mismatch

• Incorrect password hash

• Hash parameter mismatch (salt/iterations)

Solutions:

1. Verify passwords match exactly:

   # Server config
   [server]
   password = my_password
   
   # Client config
   [network]
   password = my_password
   

2. Reset password to plaintext on both sides

3. Delete hashed password from server config and restart

4. Use environment variable to override:

   export PASSWORD="my_password"
   

5. Check for trailing spaces or special characters

Invalid Token (UDP)

Symptoms:

WARNING: Invalid authentication token

Solutions:

1. Synchronize system clocks (must be within 60 seconds)

2. Request auth parameters from server first

3. Verify password matches

4. Check network isn’t modifying packets

Gamepad Issues

Gamepad Not Detected

Symptoms:

ERROR: Failed to initialize gamepad

Solutions:

1. List available gamepads:

   import pygame
   pygame.init()
   pygame.joystick.init()
   print(f"Gamepads found: {pygame.joystick.get_count()}")
   

2. Try different joystick index:

   padrelay-client --joystick-index 1
   

3. Test gamepad in other applications

4. Check USB connection

5. Install gamepad drivers

6. Try different USB port

Buttons Not Working

Symptoms:

• Some buttons don’t respond

• Buttons mapped incorrectly

Solutions:

1. Use key mapper to create custom mapping:

   padrelay-keymapper --output my_mapping.ini
   

2. Manually check button indices in pygame

3. Verify button mapping in server config

4. Test gamepad in Windows game controller settings (joy.cpl)

Axes Inverted or Wrong

Symptoms:

• Pushing up moves stick down

• Left/right reversed

Solutions:

1. Invert axes in config:

   [axis_options]
   invert_left_y = true
   invert_right_y = true
   

2. Remap axes with key mapper

3. Adjust dead zone if stick drifting:

   [axis_options]
   dead_zone = 0.15
   

Virtual Gamepad Issues

Virtual Gamepad Not Appearing

Symptoms:

• No virtual gamepad in Windows game controller settings

• Server starts but no gamepad visible

Solutions:

1. Verify ViGEmBus is installed:

   • Open Device Manager

   • Look for “Nefarius Virtual Gamepad Emulation Bus”

2. Reinstall ViGEmBus:

   • Download from https://github.com/ViGEm/ViGEmBus/releases

   • Run installer as administrator

   • Restart computer

3. Check vgamepad import:

   import vgamepad
   gamepad = vgamepad.VX360Gamepad()  # Should not raise error
   

4. Run server as administrator (sometimes needed)

5. Check server logs for vgamepad errors

Gamepad Input Lag

Symptoms:

• Noticeable delay between physical and virtual input

Solutions:

1. Use UDP protocol for lower latency

2. Increase update rate:

   [client]
   update_rate = 120
   

3. Use wired connection instead of Wi-Fi

4. Reduce network latency:

   ping 192.168.1.100  # Should be <10ms
   

5. Close bandwidth-intensive applications

6. Check CPU usage on both machines

TLS/SSL Issues

TLS Handshake Failed

Symptoms:

ERROR: TLS handshake failed
ERROR: SSL: WRONG_VERSION_NUMBER

Solutions:

1. Ensure TLS setting matches on client and server:

   # Both enabled
   padrelay-server --enable-tls
   padrelay-client --enable-tls
   
   # Or both disabled
   padrelay-server --disable-tls
   padrelay-client --disable-tls
   

2. Check certificate validity:

   openssl x509 -in ~/.padrelay/certs/server.crt -noout -dates
   

3. Synchronize system clocks

4. Update Python and OpenSSL:

   pip install --upgrade cryptography
   

5. Regenerate certificates:

   rm ~/.padrelay/certs/server.*
   # Restart server to generate new certificates
   

Certificate Errors

Symptoms:

ERROR: Certificate file not found
ERROR: Permission denied reading certificate

Solutions:

1. Let PadRelay auto-generate certificates (remove custom cert paths)

2. Fix permissions:

   chmod 600 ~/.padrelay/certs/server.key
   chmod 644 ~/.padrelay/certs/server.crt
   

3. Verify certificate files exist

4. Check paths in configuration are correct

Performance Issues

High CPU Usage

Causes:

• Update rate too high

• Inefficient input processing

• Too many clients connected

Solutions:

1. Reduce update rate:

   [client]
   update_rate = 30  # Lower from 60
   

2. Close unnecessary applications

3. Use UDP instead of TCP

4. Check for busy loops in logs

High Bandwidth Usage

Solutions:

1. Reduce update rate

2. Use UDP (less overhead than TCP)

3. Disconnect unused clients

4. Check for message flooding in logs

Rate Limiting Issues

Rate Limit Exceeded

Symptoms:

ERROR: Rate limit exceeded, connection blocked

Causes:

• Update rate higher than server allows

• Multiple clients from same IP

• Rate limit settings too strict

Solutions:

1. Increase server rate limits:

   [server]
   max_requests = 200      # For TCP
   max_requests = 12000    # For UDP
   

2. Reduce client update rate

3. Wait for block duration to expire

4. Use different client IP addresses

Protocol Issues

Protocol Version Mismatch

Symptoms:

ERROR: Protocol version mismatch

Solutions:

1. Update both client and server to same version:

   pip install --upgrade padrelay
   

2. Check versions:

   padrelay-client --version
   padrelay-server --version
   

UDP Packet Loss

Symptoms:

• Intermittent input drops

• Occasional missing inputs

Solutions:

1. Switch to TCP for reliability

2. Improve network quality (use wired connection)

3. Reduce network congestion

4. Lower update rate to reduce packet rate

Installation Issues

vgamepad Installation Fails

Symptoms:

ERROR: Failed building wheel for vgamepad

Solutions:

1. Ensure using Windows (vgamepad requires Windows)

2. Install Visual C++ Build Tools

3. Update pip:

   python -m pip install --upgrade pip
   

4. Install pre-built wheel if available

pygame Installation Issues

Linux:

# Ubuntu/Debian
sudo apt-get install python3-dev libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
pip install pygame

macOS:

brew install sdl2 sdl2_image sdl2_ttf sdl2_mixer
pip install pygame

Windows:

Usually works without issues. If not:

pip install pygame --upgrade

Debug Mode

Enabling Debug Logging

# Linux/macOS
export PADRELAY_DEBUG=1
padrelay-server --config server_config.ini

# Windows PowerShell
$env:PADRELAY_DEBUG="1"
padrelay-server --config server_config.ini

# Windows Command Prompt
set PADRELAY_DEBUG=1
padrelay-server --config server_config.ini

What Debug Mode Shows

• SSL/TLS handshake details

• Authentication challenge/response

• Connection state changes

• Message parsing and validation

• Certificate information

• Detailed error traces

Reading Debug Logs

Look for:

• ERROR: Critical failures

• WARNING: Potential issues

• DEBUG: Detailed diagnostic info

• Stack traces: For exceptions

Common Log Messages

Understanding Warnings

“Password is weak”

• Not critical, but consider using stronger password

• See password strength recommendations

“Configuration file is world-readable”

• Security risk if file contains passwords

• Fix with: chmod 600 config.ini

“Certificate expires in X days”

• Renew certificate soon

• Auto-generated certificates valid 365 days

Understanding Errors

“Rate limit exceeded”

• Client sending too many requests

• Increase rate limits or reduce update rate

“Invalid message format”

• Corrupt message or protocol mismatch

• Check versions match

• Check network isn’t corrupting packets

“Failed to create virtual gamepad”

• ViGEmBus not installed or not working

• Reinstall ViGEmBus

• Run as administrator

Getting Help

Before Asking for Help

1. Check this troubleshooting guide

2. Review logs with debug mode enabled

3. Search existing GitHub issues

4. Verify using latest version

Reporting Issues

When reporting issues, include:

1. PadRelay version: padrelay-client --version

2. Operating systems: Client and server OS

3. Python version: python --version

4. Configuration: Sanitized config files (remove passwords)

5. Logs: Relevant log excerpts with debug enabled

6. Steps to reproduce: How to trigger the issue

7. Expected behavior: What should happen

8. Actual behavior: What actually happens

Where to Get Help

• GitHub Issues: https://github.com/ssh-den/PadRelay/issues

• Documentation: https://padrelay.readthedocs.io

• Email: sshden@duck.com (for security issues)

See Also

• Client Guide - Client configuration guide

• Server Guide - Server configuration guide

• TLS/SSL Setup Guide - TLS/SSL setup

• Security - Security considerations