Troubleshooting

How to diagnose

Most MacKeyHost problems fall into one of three buckets:

1. Discovery — vmux on Vision Pro can't see the Mac at all.
2. Permissions — they pair, but the Mac counter doesn't tick or events don't reach apps.
3. Behavior — events arrive but produce the wrong result (modifiers, missing keys, weird characters).

Start with the bucket that matches your symptom.

Bucket 1: discovery

Symptom: Mac doesn't appear in vmux's keyboard target picker

If discovery still fails after the basics, restart both apps. If that fails, restart the Vision Pro — visionOS occasionally wedges its MPC daemon and a reboot is the only recovery.

Symptom: Mac appears, then disappears from the picker

The advertiser is dropping in and out. Most common causes:

• The Mac is going to sleep while idle. System Settings → Energy → Prevent automatic sleeping when the display is off, while you pair.
• Wi-Fi roaming between two access points on the same SSID. AWDL doesn't always survive a roam. Move closer to one AP.
• Battery saver / Low Power Mode on the Mac. Disable while pairing.

Symptom: pairing takes 30 seconds or more

Likely a fall-through from AWDL → infrastructure Wi-Fi → Bluetooth. Make sure both devices have Wi-Fi on and are on the same network. If the Mac is on Ethernet only, AWDL won't work — Wi-Fi must be enabled on the Mac even if you don't use it for internet.

Bucket 2: permissions

Symptom: paired and event counter ticks, but nothing types in the Mac app

Accessibility permission is missing or has been silently revoked. This is the most common single problem.

1. Look at the bottom of the MacKeyHost window. If the orange Accessibility Permission Required banner is showing, that's the cause.
2. If the banner is not showing but events still don't land, macOS may be confused about the grant. Open System Settings → Privacy & Security → Accessibility, find vmux Mac Keyboard, toggle it off, then on again. macOS will re-prompt for password/Touch ID.
3. Quit MacKeyHost and relaunch. Some macOS releases require a relaunch for the new permission to take effect.

Symptom: Accessibility was working, broke after a macOS update

Apple invalidates Accessibility grants on some major macOS updates as a security measure. Re-enable in System Settings → Privacy & Security → Accessibility. If the entry is greyed out or missing, remove it with the minus button and re-add by toggling MacKeyHost in. Relaunch the app.

Symptom: Accessibility was working, broke after MacKeyHost updated

Code-signing changes between versions can invalidate the grant. Same fix as above — toggle off, toggle on, relaunch.

Symptom: events from Vision Pro never arrive at MacKeyHost (counter stays at 0)

The session looks paired (badge is green) but no events are crossing. Try:

If the Mac side stays at zero events with a fresh session, restart MacKeyHost.

Bucket 3: behavior

Symptom: modifiers behave wrong (Cmd does Ctrl, etc.)

The wire format encodes Cmd, Ctrl, Option, and Shift as four independent flags. There is no automatic remap. If Cmd+C on the spatial keyboard is producing Ctrl+C on the Mac, the most likely cause is a custom Mac keyboard remap — System Settings → Keyboard → Keyboard Shortcuts → Modifier Keys may have Cmd and Ctrl swapped on the Mac. MacKeyHost respects that remap because it operates above the level of CGEvent. Reset the modifier mapping to default.

If only some shortcuts misbehave, check System Settings → Keyboard → Keyboard Shortcuts → App Shortcuts for a custom binding that conflicts.

Symptom: a specific letter or symbol comes out wrong

Text events ride as Unicode codepoints, not as virtual key codes. If é arrives as e´ or vice versa, the Mac's input source is intercepting the codepoint to compose with a dead key. Switch input sources to U.S. (or whatever matches your spatial keyboard layout) in the menu bar input picker.

If a punctuation character is wrong, it is almost always an input-source mismatch — non-Latin layouts (Russian, Greek, Arabic) particularly will mis-map ASCII letters.

Symptom: function keys don't do what they do on a real keyboard

F1–F12 ride as virtual key codes, so the Mac sees them exactly as it would from a hardware keyboard. The difference: hardware Macs default the F-row to brightness/volume/Mission Control, not F1–F12, unless you hold Fn (or invert the default in System Settings → Keyboard → "Use F1, F2, etc. keys as standard function keys").

The spatial keyboard sends pure F-keys without any Fn equivalent. If you want media-key behavior, use the Mac's built-in F-row directly — it isn't reachable through MacKeyHost.

Symptom: certain keys are silently missing

Keys not in the special-key map (see Input injection) and not representable as Unicode text won't be transmitted. This includes:

• Caps Lock — no spatial-keyboard equivalent. Use Shift latching.
• Fn — same.
• Eject, power, brightness, volume, media controls — handled by hardware before the event tap; cannot be synthesized.
• Numeric keypad keys — sent as the corresponding digit/symbol, not as numpad-N virtual keys. Apps that distinguish (some games, accounting apps) won't recognize them as keypad presses.

Symptom: pointer is laggy or jumpy

Latency is dominated by the MPC transport.

Symptom: cursor is stuck and won't move past a screen edge

Cursor position is clamped to the bounds of the main display only. If you have multiple displays, the pointer is restricted to the primary. There is no current option to extend it across displays. Make the display you want to control the primary in System Settings → Displays.

Symptom: typing feels rate-limited under heavy use

MacKeyHost caps incoming events at 100 per second. Hand typing tops out around 10 events/sec, so this only triggers if a script is sending or if the spatial keyboard is glitching. If you need to inject many characters fast, paste from the Mac's clipboard rather than typing key-by-key.

When to restart what

Triage in this order — cheap fixes first.

1. Toggle the Mac target off and on in vmux.
2. Quit and relaunch MacKeyHost.
3. Force-quit and relaunch vmux on Vision Pro.
4. On both devices, cycle Wi-Fi off and back on.
5. On both devices, cycle Bluetooth off and back on.
6. Restart the Vision Pro.
7. Restart the Mac.

Steps 1–3 fix maybe 80% of issues. Steps 4–5 cover transient transport wedges. Steps 6–7 are last resort for OS-level peer-to-peer daemon hangs.

What state MacKeyHost keeps

Almost none. The app stores no preferences, no paired-device list, no event log between launches. The two pieces of state that persist are:

• The Accessibility entry in System Settings (you control this; remove with the minus button).
• The Local Network permission grant (toggle in Privacy & Security).

Quitting and relaunching is therefore safe — there is nothing to corrupt and nothing to "reset." If a clean reset is what you want, just quit and relaunch.

Capturing details for support

If you need to file a bug, include:

• macOS version (Apple menu → About This Mac).
• visionOS version on the Vision Pro (Settings → General → About).
• MacKeyHost version (Apple menu while MacKeyHost is frontmost → About vmux Mac Keyboard).
• vmux version on the Vision Pro (vmux → Settings → About).
• Whether other Macs on the network show the same behavior.
• The state shown in the MacKeyHost window when the failure occurs (badge color, event counter value, last event description).

The badge state and counter are the single most useful piece of triage data. Counter at zero with green badge points to a Vision Pro side problem; counter ticking with no Mac result points to Accessibility on the Mac; badge stuck on Advertising points to discovery.

Related

• Getting started — first-run pairing.
• Pairing with Vision Pro — discovery details.
• Input injection — modifier rules and event mapping.
• Security and permissions — what the permissions actually do.