Skip to content

Troubleshooting

Jump to bottom
Ken Tobias edited this page Jun 16, 2026 · 8 revisions

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 (some networks block non-TCP)
  • The server keeps state for 30 minutes; if more than 30 minutes elapsed, the session is gone

UDP blocked by firewall

If your network blocks UDP, etr cannot work. 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 checks the protocol version during handshake and will reject a mismatched server. Ensure both etr and etrs are the same version:

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 packet traces during debugging:

ssh user@host
etrs -vvv
# In another terminal:
echo "SESSION_ID/PASSKEY/xterm-256color" | etr --server-path /dev/stdin user@host

Clone this wiki locally