Skip to content

Troubleshooting

Jump to bottom
Ken Tobias edited this page Jul 10, 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

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

TUI program fails with "No UTF-8 locale" or wrong colors

When running a remote command (etr host btop), the shell is non-interactive and doesn't source ~/.bashrc/~/.zshrc, so locale and color env vars may not be set.

etr automatically forwards LANG, LC_ALL, LC_CTYPE, COLORTERM, and TERM_PROGRAM from your local environment. If the program still complains:

  1. Check your local locale is set: echo $LANG — should be something like en_US.UTF-8
  2. Override explicitly: etr --env LANG=en_US.UTF-8 user@host btop
  3. For color depth: etr --env COLORTERM=truecolor user@host btop

DISPLAY and WAYLAND_DISPLAY are not forwarded — GUI programs that require a display server will not work over etr host cmd.

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.

Windows: session output doesn't display / terminal looks frozen

etr uses crossterm for raw-mode terminal I/O, which requires a real Win32 console. Git Bash/mintty (and similar MSYS2 terminals) don't provide one, so raw-mode output silently doesn't render even though the session is actually connected and working.

Fix: run etr from a native console — PowerShell, Command Prompt, or Windows Terminal — instead of Git Bash.

Windows: -X/-Y fails immediately

X11 forwarding requires Unix domain sockets and is not supported on Windows. etr rejects -X/-Y at startup with a clear error rather than attempting to connect.

Windows: Backspace acts like delete / doesn't erase

From a Windows etr client to a Unix host, Backspace could act like a delete, fail to erase, or show ^?/^H. The Windows console delivers legacy key codes to raw byte reads — Backspace as 0x08 — while a Unix PTY expects the xterm convention 0x7f (DEL) to match the default stty erase.

Fixed in v0.6.3+. The client now puts the Windows console into virtual-terminal mode, so keys are sent as the xterm byte sequences the remote expects (Backspace → DEL). Upgrade the Windows etr client to 0.6.3 or later:

etr --version

If you can't upgrade, most Windows terminals let you remap the Backspace key to send DEL (0x7f) as a workaround.

Windows: first line of typing isn't echoed until you press Enter

Known, unresolved (issue #54). From a Windows etr client, the remote prompt appears normally, but the first line you type isn't echoed until you press Enter — after which the whole line appears and runs, and the session behaves normally from then on. It does not happen linux→linux and isn't shell-specific. The keystrokes do reach the server, but the Windows client batches the first line into a single send instead of delivering it per keystroke. There is no workaround yet beyond the (harmless) extra Enter; progress is tracked in the issue.

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.

Clone this wiki locally