-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
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@hostetr'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@hostIf 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.
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)"
fiWhen 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:
- Check your local locale is set:
echo $LANG— should be something likeen_US.UTF-8 - Override explicitly:
etr --env LANG=en_US.UTF-8 user@host btop - 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.
Check the server log on the remote host:
cat ~/.local/state/etr/etrs.logCommon causes:
- The remote shell (
$SHELL) exits immediately due to a broken.bashrc/.zshrc - PTY allocation failed (rare; try on a fresh server account)
Verbose logs go to a file during a live session to avoid corrupting the terminal display.
tail -f ~/.local/state/etr/etr.logThe log path is printed to stderr before the session starts.
- 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 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
etr and etrs must be the same version. Ensure both are up to date:
etr --version
ssh user@host etrs --versionIf 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+:
etrshandles 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 processIf the PID is gone, the entry is stale and harmless.
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.
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.
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 --versionIf you can't upgrade, most Windows terminals let you remap the Backspace key to
send DEL (0x7f) as a workaround.
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.
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 -vvvThen connect with etr -vvv user@host in another terminal.