Debugging

Verbose Mode

tuimble --verbose                # (planned)

Common Issues

No audio devices found

python3 -c "import sounddevice; print(sounddevice.query_devices())"

Check that portaudio is installed and devices are accessible.

opuslib import error

python3 -c "import opuslib"

If this fails, install libopus: apt install libopus0

Kitty protocol not detected

Verify terminal supports the Kitty keyboard protocol. Known working: Kitty, WezTerm, Ghostty, foot.

evdev permission denied

ls -la /dev/input/event*
groups                           # should include 'input'

Add user to input group: sudo usermod -aG input $USER

Certificate errors

If the server requires client certificates:

# Verify cert/key pair
openssl x509 -in cert.pem -noout -subject -dates
openssl rsa -in key.pem -check -noout

Both certfile and keyfile must be PEM-encoded
Paths must be absolute or relative to the working directory
Key must not be passphrase-protected (pymumble limitation)
If the server uses a self-signed CA, pymumble verifies by default

Connection refused

Verify server address and port
Check firewall allows outbound TCP/UDP to port 64738
Test with: nc -zv <host> 64738

Connection drops / reconnection

When tuimble loses connection, it retries automatically with backoff. The chatlog shows each attempt:

✗ disconnected from server
reconnecting in 2s (attempt 1/10)...
✗ attempt 1: network error: [Errno 111] Connection refused
reconnecting in 4s (attempt 2/10)...
✓ connected as myname

Common causes:

Server restart — normal, reconnect succeeds when server is back
Network loss — check connectivity, tuimble retries automatically
Auth timeout — server may drop idle connections; reconnect handles this
"rejected" with no retry — wrong password or certificate issue

If reconnection fails after 10 attempts, press F5 to retry manually. Update config.toml if server details changed.

2.0 KiB Raw Blame History