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

Force-disconnect when the server is unresponsive

If the remote machine has crashed or the network has died and the client is stuck, use the escape sequence:

~.

Type ~ followed by . at the start of a line (or immediately after connecting). The client exits immediately without waiting for the server.

zellij (or other login-shell tools) doesn't auto-start in etr sessions

etr spawns the remote shell as a login shell (argv[0] = -zsh), so .zprofile and .zlogin are sourced — just like SSH.

If your .zlogin checks $SSH_CONNECTION to decide whether to start zellij, it will work: etrs passes SSH_CONNECTION from the SSH bootstrap session into the shell environment.

Make sure your condition also guards against loopback connections (etr localhost) by checking the client IP in the first field of SSH_CONNECTION:

if [[ -n "$SSH_CONNECTION" || -n "$ETR_CONNECTION" ]] \
    && [[ "${SSH_CONNECTION%% *}" != "127."* ]] \
    && [[ "${SSH_CONNECTION%% *}" != "::1" ]] \
    && [[ -z "$ZELLIJ" ]]; then
    exec zellij attach -c "$(hostname)"
fi

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

Stale entries in who / last

If who or last shows you logged in when you're not, or shows duplicate entries, the etrs session exited without writing a clean logout record.

• v0.4.5+: etrs handles SIGTERM and SIGHUP and writes the logout record before exiting, so this should not occur for normal kills.
• Older versions / SIGKILL: SIGKILL cannot be caught; no cleanup is possible. The stale entry will eventually expire from the utmp database when the system is rebooted or a new session takes the same PTY slot.

To verify which session is stale, compare the PID in the who output against running processes:

who          # shows "ktobias pts/3  ... (10.0.0.1 via etr [12345])"
ps -p 12345  # check if PID 12345 is still an etrs process

If the PID is gone, the entry is stale and harmless.

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.