Troubleshooting

Diagnose first, fix second

Almost everything on vmuxWatch routes through the vmuxPhone relay. When something is wrong, three pieces of information narrow the cause down quickly:

The Status section in the watch's session list — does it say Phone reachable or Phone not reachable?
The connection label on the terminal page — Connected, Connecting…, or a specific error reason.
Whether the iPhone shows the same problem (same red banner, same disconnected state) when you check it.

If the iPhone is wrong, fix the iPhone first; the watch is a viewer.

Watch shows no sessions

"Phone not reachable" stays on

The WatchConnectivity link is not active. Try in this order:

Open the Watch app on your iPhone. Confirm the watch is paired and connected (top-of-app status icon).
Open vmuxPhone on the iPhone — iOS sometimes only wakes WatchConnectivity after the phone app has run once this session.
Make sure both devices are unlocked at least once since the last reboot. WatchConnectivity does not work before first unlock.
Confirm Bluetooth is on, on both devices. Or, alternatively, that both are on the same Wi-Fi network.
Force-quit vmuxWatch (press the side button to bring up the app switcher, swipe vmux up) and re-open it.

Stubborn cases: restart the watch, then the iPhone, in that order.

"Phone reachable" but Phone Sessions is empty

The link is alive but vmuxPhone has no open windows. This is correct if you have not connected to anything on the iPhone today. Tap a host under Hosts On Phone to ask the iPhone to open one — but be aware: if the host has never been opened on the iPhone, the watch will refuse and prompt you to "Open the session on phone first, then continue it here." That is intentional; the iPhone needs its credentials warm before it can hand off a session.

Hosts On Phone is empty

vmuxPhone has no saved hosts. Open vmuxPhone and add at least one. The watch updates within a second of saving.

Phone Sessions is empty but the iPhone clearly has windows

The relay has not finished its bootstrap. Pull your wrist out of your sleeve to wake the watch, wait two seconds, and the watch should poll the iPhone again. If it still does not catch up, force-quit vmuxWatch and re-open it.

Input is not arriving on the server

Dictation hears me but nothing happens

You are likely in Cmd mode, dictating a phrase the resolver does not recognize, and the fallback parser is not classifying any of the words as keystrokes.

Switch to Text mode if you are trying to send prose. The yellow MIC CMD / cyan MIC TXT indicator next to the Cmd / Text toggle tells you which mode you are in.

Tmux buttons do nothing on the server

Two common causes:

The session is not running tmux. The buttons send tmux key sequences regardless; if the shell is plain bash, you will see literal output like ^B or : typed at the prompt.
You have changed the tmux prefix away from Ctrl-B on the remote machine. The buttons always send Ctrl-B. Either restore the default prefix, or use dictation phrases instead — those are interpreted by the iPhone's voice parser and respect your tmux config.

Mini keyboard taps land in the wrong place

The watch always sends keys to the active window. The active window is the one currently shown on the terminal page (or the iPhone's selected window if no terminal page is in front). If you have just swiped between windows and the screen has not finished animating, give it a moment so the watch can register the new selection on the iPhone.

Special keys do not work

The watch sends Esc, Tab, Enter, Backspace, and arrows. Anything beyond that — Function keys, Cmd-anything, mouse events — is not available from the watch. Use vmuxPhone or another vmux client for those.

"Repeat" sends the wrong thing

Rpt always re-sends the last meaningful dictation in Cmd mode for the current host. It is per-host, not global. If you switched hosts and dictated nothing yet, it shows the previous host's command until you dictate a new one. This is intentional — you usually want to repeat the last make, not whatever you typed at a different machine.

Connection failures

The iPhone did not respond to a focus or open request within eight seconds. Causes:

iPhone screen is locked and iOS routed the request to a Notification Center banner. Pick up the iPhone, tap the banner, and complete Face ID.
iPhone is out of range and not on the same Wi-Fi network. Move closer.
vmuxPhone has crashed in the background. Open it on the iPhone.

Tap the reload icon in the control row to retry.

"No route to host" / "Connection refused" / "Timed out"

These come from the iPhone's SSH/Mosh layer, not the watch. The watch shortens them so they fit on the small screen. Fix the iPhone-side network or hostname; once the iPhone connects, the watch updates automatically.

"Authentication failed"

The iPhone's credentials for this host are wrong. Open vmuxPhone, edit the host, fix the password or key reference, and reconnect from the iPhone. The watch will follow.

App problems

The watch app crashes on launch

Force-quit and re-open. If it persists:

Reboot the watch (long-press side button → Power Off → power back on).
Delete vmuxWatch from the watch (long-press app icon → Delete) and reinstall via the Watch app on iPhone.
As a last resort, unpair and re-pair the watch with the iPhone. This rebuilds the WatchConnectivity state.

The terminal page is blank

Snapshot has not arrived yet. Wait one or two seconds. If it stays blank for more than five seconds:

Confirm the iPhone-side window is actually connected (open the iPhone, check that the same session has output).
Tap the reload icon to toggle the iPhone-side connection.
Switch display modes (Dn ↔ Rd) — that recomputes viewport and re-asks the iPhone for a fresh snapshot.

Output is stale

WatchConnectivity sometimes batches updates aggressively when the watch is on a charger or backgrounded. The watch refreshes when:

You raise your wrist.
You re-enter the session list view (which polls every two seconds while it is on screen).
The iPhone pushes a new snapshot (debounced ~120 ms).

If output looks stuck, swipe back to the session list and back into the terminal — that re-arms the polling and fetches a bootstrap.

Manual-connect saved hosts disappeared

Hosts saved through Connect Manually live on the watch only, in its app-support directory. They survive app launches but not app deletion. If you reinstall vmuxWatch, you will need to recreate those manual entries. Hosts that came from the iPhone (under Hosts On Phone) are unaffected — they are sourced from vmuxPhone every session.

Battery drain concerns

Watch battery dropping faster than usual

A few common causes:

Always-On terminal page. If you keep the terminal page in front while the watch is on your wrist for long stretches, the screen renders snapshots constantly and burns battery faster than glancing. Drop your wrist to let the screen idle between glances.
Very chatty sessions. A session producing constant output (tail -f of a busy log, an active build) means the relay sends a snapshot every ~120 ms while you are looking. The relay coalesces these but it still costs.
Dictation. Each dictation invocation wakes the microphone and the speech recognizer. Heavy dictation use drains battery noticeably.
Bluetooth headphones in use simultaneously. Bluetooth contention with the iPhone can keep the radios busier; not vmux's fault, but it shows up in the same battery report.

Reduce drain

Drop your wrist between glances. The watch turns its screen off after a few seconds and the relay coalesces snapshots until the next wake.
Close unused windows on the iPhone. The relay does not send snapshots for windows that do not exist; fewer windows means less traffic.
Use Dense (Dn) display only when you really need it; Readable (Rd) costs the same but its lower row count means slightly fewer cells per snapshot.
Switch to vmuxPhone or vmux on visionOS for sessions you actually need to read for more than a glance.

When all else fails

Restart the watch.
Restart the iPhone.
Reinstall vmuxWatch from the Watch app.
Re-pair the watch with the iPhone in the iOS Watch app.

If a problem persists after all four, the issue is likely on the iPhone side. See vmuxPhone — Troubleshooting.

Pairing with iPhone — how the link works and what can break it.
Viewing sessions — what each label and badge means.
Input on watch — what you can and cannot type from the wrist.