Troubleshooting

Troubleshooting

etrs: command not found

The remote SSH session has a minimal PATH that doesn't include ~/.cargo/bin.

Fix: add to ~/.bashrc or ~/.zshrc on the remote host (outside any if [ -z "$PS1" ] interactive-only guard):

export PATH="$HOME/.cargo/bin:$PATH"

Or specify the full path explicitly:

etr --server-path /home/user/.cargo/bin/etrs user@host

SSH asks for a password

etr's bootstrap SSH connection runs non-interactively — it can't prompt for a password.

Fix: set up passwordless SSH with a key pair:

ssh-keygen -t ed25519
ssh-copy-id user@host

Session connects but immediately disconnects

Check the server log on the remote host:

cat ~/.local/state/etr/etrs.log

Common causes:

• The remote shell ($SHELL) exits immediately due to a broken .bashrc/.zshrc
• PTY allocation failed (rare; try on a fresh server account)

etr -v shows nothing / logs appear blank

Verbose logs go to a file during a live session to avoid corrupting the terminal display.

tail -f ~/.local/state/etr/etr.log

The log path is printed to stderr before the session starts.

Session doesn't reconnect after a network drop

• Wait up to 15 seconds — the client reconnects on heartbeat timeout, not immediately
• Check that UDP traffic is allowed between client and server (QUIC runs over UDP; some networks block non-TCP)
• The server keeps state for 30 minutes; if more than 30 minutes elapsed, the session is gone

QUIC (UDP) blocked by firewall

QUIC runs over UDP. If your network blocks outbound UDP on high ports, etr cannot connect. There is no TCP fallback. Options:

• Ask your network admin to allow UDP on high ports
• Use a VPN that permits UDP

Version mismatch between etr and etrs

etr and etrs must be the same version. Ensure both are up to date:

etr --version
ssh user@host etrs --version

Checking the server log

The server log is at ~/.local/state/etr/etrs.log on the remote host:

ssh user@host 'tail -50 ~/.local/state/etr/etrs.log'

Run etrs -vvv manually to see full stream traces during debugging:

ssh user@host etrs -vvv

Then connect with etr -vvv user@host in another terminal.