Troubleshooting
Common vmux problems and how to fix them, organized by what you were trying to do.
Find the section that matches what is going wrong. Each section is a table with a Problem you can recognize, the Likely cause, and the Fix. If the table does not have your symptom, use Export Diagnostics in Settings to copy a sanitized JSON report to your clipboard, then attach it to a support ticket.
| Problem | Likely cause | Fix |
|---|
| "Connection timed out" after 15 seconds | Host is unreachable or the port is wrong. | Verify the host responds to ping from another device. Check the port — most servers use 22. |
| "Authentication failed" with the right password | Server has password auth disabled, or the wrong username. | Check /etc/ssh/sshd_config on the server for PasswordAuthentication yes. Verify your username. |
| "Host key verification failed" / "Host key changed" | The server's identity changed since the last connect — could be a legitimate reinstall, or a man-in-the-middle attempt. | Confirm with the server admin. If the change is expected, remove the cached host key entry. Do not click through this without verifying. See Security. |
| Connection drops within a minute, repeatedly | Idle timeout on a NAT or firewall along the path, or a flaky Wi-Fi. | Switch to Mosh — it survives short interruptions. If you cannot use Mosh, enable SSH keepalive (ServerAliveInterval 30) on your client (vmux sends keepalives by default). |
| "Permission denied (publickey)" with key auth | Public key is not in the server's authorized_keys, or the file permissions are wrong. | Append the key to ~/.ssh/authorized_keys on the server, then chmod 600 ~/.ssh/authorized_keys and chmod 700 ~/.ssh. See SSH Keys. |
| First connect prompts for a password every time, even with a saved host | The password was not saved to Keychain. | Edit the saved host, re-enter the password, and tap Save. |
| Connection works on Wi-Fi but fails on cellular | Cellular network blocks SSH (some carriers do) or has tighter MTU. | Use a VPN, or switch transport to Mosh. |
| Problem | Likely cause | Fix |
|---|
| "mosh-server not found on remote host" | mosh-server is not installed, or installed in a non-standard path. | Install via your package manager, or override the Server command field in the host's Mosh settings. See Mosh. |
| Connection hangs after "SSH bootstrap starting" | UDP traffic is blocked between you and the server. | Open the configured UDP port range (default 60000:61000) on every firewall. Verify with Mosh Diagnostics. |
| "Mosh bootstrap failed" | Locale on the remote is not UTF-8, or mosh-server crashed at startup. | Run locale -a | grep -i utf on the remote. Set LANG=en_US.UTF-8 in your remote shell init. |
| Garbled accents or emoji over Mosh | Same as above — UTF-8 misconfiguration. | Run Mosh Diagnostics → Encoding scenario to confirm. |
| Mosh disconnects when headset goes to sleep | Mosh handles this normally — dropping suggests a deeper issue. | Run the Mosh Diagnostics Lifecycle scenario to reproduce and capture a report. |
For deep failure analysis, see Mosh Diagnostics — it can pinpoint the exact step that is breaking.
| Problem | Likely cause | Fix |
|---|
| Picker shows "JetBrains Mono" but no Nerd Font icons in vim/tmux | The selected font is the built-in JetBrains Mono, not a Nerd Font variant. | In Settings, open the font picker and pick a font with "Nerd Font" in the name. |
| A font I imported is missing from the picker | The font file is not a .ttf or .otf, or is corrupted. | Re-import a fresh .ttf. See Fonts. |
| Powerline characters look misaligned | The font is not patched for Powerline / Nerd Font glyphs, or your remote shell uses a different font expectation. | Use a Nerd Font and run nerdfetch or similar to verify glyphs render. |
| Box-drawing characters look broken | Theme color and background are too close in luminance. | Bump opacity, or switch Themes. |
| Text is fuzzy at small sizes on Vision Pro | Below 12pt, anti-aliasing limits readability. | Increase Font Size to 14pt+ and use Cmd+- if the resulting view is too zoomed. |
| Problem | Likely cause | Fix |
|---|
| Headset gets noticeably warm | CRT effects use significant GPU. | Disable CRT effects from Settings → CRT Effects → CRT Effect off. |
| Frame rate drops in dim rooms with CRT on | Bloom and chromatic aberration are expensive in dark scenes. | Set Bloom to 0% and Chromatic to 0%, or disable CRT entirely. |
Scrolling lags after cat-ing a huge file | Scrollback buffer churn on extreme bursts. | Use tail or paginate. Clear scrollback with Cmd+K. |
| App feels sluggish after running for hours | Memory bloat from many panes / large scrollback. | Close panes you no longer need, or restart vmux. |
| Multiple windows make typing feel laggy | Each window runs its own GPU pipeline. | Close unused windows; switch Pane Organization to Pane Tabs. |
| Problem | Likely cause | Fix |
|---|
| Cannot enter immersive mode — toggle does nothing | Another app holds the immersive space. | Close the other immersive app (Cinema, Encounter Dinosaurs, etc.) and try again. |
| Stuck in immersive mode, gesture does not exit | An app focus issue swallowed the gesture. | Press the Digital Crown to dismiss the space. If that fails, force-quit vmux from the visionOS app switcher. |
| Desk Cutout is in the wrong spot | Your seated viewpoint changed since you tuned the cutout. | Recenter your view (Digital Crown long-press), then nudge Forward and Left/Right in the cutout settings until aligned. See Immersive Mode. |
| Floor grid is invisible | Grid Opacity is at the floor of the range, or the grid is below your view. | In settings, raise Grid Opacity to 4%. |
| Black void shows tiny visible patches | visionOS Persona awareness flashing nearby people. | Expected behavior — visionOS will not let you fully hide other humans. |
| Problem | Likely cause | Fix |
|---|
| Mic button does nothing on first tap | First-run permission prompt was missed. | Grant microphone and speech recognition permissions in iOS Settings → vmux. |
| "control c" is interpreted as the letter C | Voice mode is set to PROSE, not CMD. | Switch to CMD mode in the voice ornament. See Voice Commands. |
| Wrong letters from NATO words | Background noise or accent affecting recognition. | Speak slowly, pause between groups, or use spelled-out letters ("c" instead of "see"). |
| App command phrase "open settings" does not run | The phrase did not exactly match a command catalog entry. | Check phrasing in Voice Commands — only listed phrases are dispatched. |
| Commands fire after every word during dictation | Long-form dictation is not in PROSE mode. | Toggle to PROSE mode for long text input; switch back to CMD for control. |
| Problem | Likely cause | Fix |
|---|
| VKeyboard does not appear when expected | The terminal is focused but VKeyboard is a separate window that needs to be opened explicitly. | Open it from the Command Palette ("Open VKeyboard") or from Settings. |
| Keys feel unresponsive to gaze | Hover Stroke opacity is too low to see the highlight, but presses are registering. | In Settings → Keyboard → VKeyboard, raise Hover Stroke Opacity. |
| Swipe typing produces gibberish | Stroke recorder does not have enough samples or hand pose is jittery. | Slow down the swipe slightly. Try fewer letters per swipe to confirm the path. See Pen Input. |
| Modifier keys do not stick | Modifiers are one-shot toggles by design. CapsLock is the only persistent one. | Tap modifier, then press the next key. See Keyboard Shortcuts. |
| VKeyboard floats too far / too close | Pitch, Floor Lift, and Front Offset settings are off. | Adjust in Settings → Keyboard → VKeyboard until placement feels right. Defaults: Pitch 90, Floor Lift 3 mm, Front Offset 42 mm. |
| Problem | Likely cause | Fix |
|---|
| Mac keyboard companion shows "Disconnected" | Mac and headset are not on the same network or Bluetooth is off. | Verify both are on the same Wi-Fi. Toggle Bluetooth off and on. |
| Keystrokes from Mac do not reach headset terminal | The headset window does not have focus. | Look at the vmux terminal window (eye gaze gives focus on Vision Pro) and try again. |
| Keystrokes are delayed or doubled | Network jitter, or two paired devices fighting. | Disconnect any other paired headset. Move closer to the Wi-Fi router. |
| Modifier keys (Cmd, Option) misbehave | Mac sends raw key codes; mapping depends on the Option as Meta setting. | Toggle Option as Meta in Settings — on for vim/emacs users, off for plain text input. |
| Pairing prompt never appears | The Mac companion was never installed, or its menu bar item was quit. | Reinstall and relaunch the Mac companion. See Companion Apps. |
| Problem | Likely cause | Fix |
|---|
| "No iPhone signer found" | RemoteSignerPhone is closed or out of range. | Open the app on the iPhone, keep it foregrounded, retry. See SSH Signing with iPhone. |
| Face ID prompt never appears on iPhone | Multipeer Connectivity invite did not deliver. | Toggle Wi-Fi on the iPhone off and on. Reopen the app. |
| Multiple identities on iPhone, but the wrong one is used | Server's authorized_keys only matches one of them. | Disable identities you do not want offered, in RemoteSignerPhone. |
When the table above does not cover your symptom, capture a report:
- Open Settings.
- Tap Export Diagnostics.
- Paste the resulting JSON into a support ticket or email.
The export contains app build, OS version, settings (with passwords stripped), recent log lines, and recent errors. It does not contain your hostnames, usernames, passwords, or session output.
For Mosh-specific issues, run a scenario from the Mosh Diagnostics panel and attach the resulting report file — it includes scenario-by-scenario timing and the last 8 KB of session output for the failing run.