Troubleshooting

Start with the connection

tailmux doctor personal/devbox
tailmux ssh personal/devbox hostname

If the first fails, check tailnet login, device approval, policy, host availability, and the SSH port. If only the second fails, investigate SSH authentication.

Permission denied

The remote user may differ from your local username. Save the correct one:

tailmux hosts add personal/devbox --user developer

Inspect ssh -G devbox to see the effective user, identity files, and agent configuration. With 1Password, confirm that its agent is available and that the host matches the appropriate SSH config block.

Too many authentication failures

Select one public key with IdentityFile and IdentitiesOnly yes instead of offering every key in your agent. See SSH & 1Password.

Herdr: command not found

Herdr may be installed but missing from the non-interactive shell's PATH:

tailmux ssh personal/devbox sh -lc '"$HOME/.local/bin/herdr" --version'

If that succeeds, fix the remote shell's PATH. If it fails because the file is missing, install Herdr on the host.

Profile needs login

tailmux login personal

Check the reported tailnet. Ensure you opened the URL with the intended account. Work devices may need approval before they can reach peers.

Empty discovery after restart

The node may still be receiving its peer map. Try tailmux hosts again. An empty list can also mean that the tailnet has no visible peers for this identity.

Daemon did not start

Read daemon.log in your Tailmux config directory. If TAILMUX_HOME is very long, choose a shorter location before first enrollment. A second daemon cannot own an active state directory.

After a binary update, run tailmux stop and retry. Do not delete state as a routine troubleshooting step.

Localhost redirects and forwarding

Use an unnamed forward with the original port to preserve localhost URLs:

tailmux forward personal/devbox 3000

For named HTTP URLs, first run tailmux loopback setup personal/devbox, then add --name devbox.test. Direct localhost redirects, JSON URLs and loopback cookie domains are rewritten by default. Rewrites cover only ports in that group; HTML/JavaScript, HTTPS URLs and external OAuth callback parameters are not rewritten. .test over HTTP is not automatically a secure context, so OAuth provider allowlists, Secure cookies and service workers can still require application or HTTPS setup. See forwarding.

Name does not resolve

Private named forwards use the dedicated address shown by:

tailmux loopback list

If the name is missing, rerun tailmux loopback setup <host> --name <name>. The command updates this computer's /etc/hosts and loopback interface with administrator access. .localhost cannot be used because browsers hardcode it to 127.0.0.1; use the default .test name. On macOS, setup installs a LaunchDaemon to restore the alias at boot. Rerun setup once to upgrade an older configuration. Tailmux does not register mDNS names.

Port conflict, 421, or 502

Check tailmux forwards and tailmux loopback list for existing groups and address assignments. Different boxes' named routes can share a port because they bind distinct 127.77.x.y addresses. A process listening on wildcard 0.0.0.0:<port> can still conflict with all of them. Raw TCP forwarding reserves its 127.0.0.1 port exclusively. A range conflict rejects the entire new group. Stop a group with tailmux unforward <id>.

HTTP 421 means the request's Host header does not match a named forward on that port; use its configured URL. HTTP 502 means the proxy could not reach the remote application. Confirm the app is listening on remote 127.0.0.1 at the mapped port and that SSH permits local forwarding. A running tunnel does not prove an app is listening.

Forward creation or reconnection fails

Forward creation uses batch SSH authentication. Unlock your agent and verify tailmux ssh <host> hostname. Check host SSH forwarding policy. Failed tunnels retry with capped backoff while retaining their ports. Exhausted retries remain visible in tailmux forwards; repair SSH access, then retry the saved forward or remove/recreate the group. tailmux stop stops runtime connections but retains saved definitions for the next daemon start.

Box picker shortcut does nothing

In Zellij, try Ctrl+B from normal mode or F2 when unlocked. Press Ctrl+G to leave locked mode. In tmux, use Ctrl+B, then B. Option/Alt+B requires the terminal to send Meta/Alt rather than a special character or intercept the key.

Reopen with tailmux terminal after upgrading to regenerate the dedicated configuration. Ensure fzf is installed locally. The picker needs profile discovery and may display Loading boxes… while a profile starts.

A tab uses only part of the terminal

Another attached Zellij client may have a smaller terminal. Use zellij list-sessions to find the Tailmux session, then zellij --session <session> action list-clients to inspect clients. Detach unused views with Ctrl+O, then D in those views, and revisit the affected tab. Do not kill the server to fix a sizing issue.

Blue command path or square symbols

The blue path is a Zellij pane title, not an error or remote output. Current Tailmux names new panes after their target and enables simplified UI to avoid missing arrow-font symbols. Reopen Tailmux after upgrading. Existing pane titles can be changed with Zellij's pane rename action. Current versions store routing separately, so tab/window names may also be changed.

New splits connect to the wrong box or show the chooser

Routing is stored independently of tab/window names, so renaming a tab retains its host. Older tabs that were renamed before upgrading have no recoverable routing metadata; open the intended host once from the picker to establish a routed tab. Each pane has a separate persistent remote tmux shell; tailmux herdr sessions lists Herdr sessions only.

Closed tabs come back

Earlier Tailmux versions automatically resurrected Zellij's last saved layout after its final tab closed. Update the binary and reopen with tailmux terminal. Current versions reattach to live sessions but discard exited snapshots before creating a fresh session. Detaching still preserves live tabs. This behavior is separate from tailmux herdr sessions, which lists remote Herdr processes.

New forwarding flags rejected after upgrading

An already running daemon keeps executing its previous binary. New persistent/public forwarding and isolated-loopback features require the updated daemon. Detach from sessions as needed, run tailmux stop, and start networking again. This interrupts local SSH tunnels and forwards; remote persistent sessions remain running. Reconnect Orca with tailmux orca status <host>.

For a saved named forward from an older version, run tailmux loopback setup <host> --name <saved-name-hostname> before restarting or resuming it. If restoration already failed, use tailmux forward --resume <saved-forward-name> after setup.

Public URL is unavailable

Check tailmux forwards for SSH and provider states. Install/authenticate the provider CLI, verify the configured domain and Cloudflare DNS route, and inspect the private provider log indicated by the error. A running connector process does not guarantee a working DNS route or application. For login loops, check the app's public origin and OAuth callback registration; rewriting cannot change provider allowlists.

Dashboard is missing or too small

Bare tailmux opens the dashboard only when input and output are terminals. Use tailmux dashboard explicitly, or tailmux status --json in scripts. Resize to at least 40 columns by 12 rows. Tab moves through form fields, including fields below the visible area.

Lost-packet page

A Tailmux “Right network. Wrong doorstep.” page means the request reached a Tailmux HTTP listener, but its hostname has no route there. Check the hostname and port against tailmux forwards. Browser requests receive a styled 421 page; API clients receive a plain-text error. Remote applications retain their own error pages.

“Found your box. Nobody’s home.” is Tailmux’s 502 page: the forward exists, but the remote application could not be reached. Check the remote listening port and tunnel status. Browser requests get the recovery page; API requests keep a plain-text error.