Troubleshooting

Fixes for vmux Keyboard not in the picker, keys not registering, swipe quirks, layout lag, and switching mid-type.

"vmux Keyboard" does not appear in Add New Keyboard

iOS hides custom keyboards from the picker until their host app has been launched at least once on the device.

Fix: open the vmux Keyboard app from the home screen. Wait for the welcome view to appear. Close the app. Then go back to Settings -> General -> Keyboard -> Keyboards -> Add New Keyboard... — vmux Keyboard now appears under THIRD-PARTY KEYBOARDS.

If you have used the host app before but it still does not appear:

Make sure the app is up to date in the App Store.
Reboot the iPhone or iPad. iOS occasionally caches the keyboard list.
If you migrated from a previous device via iCloud restore and never opened the host app on the new device, that is the problem — open it once.

I cannot toggle Allow Full Access

The Allow Full Access toggle on Settings -> General -> Keyboard -> Keyboards -> vmux Keyboard is off by default and you should leave it that way for the current release. There is no functionality you are missing — see Installing the keyboard for the details.

If you specifically want to enable it for testing and the toggle is greyed out:

The device may be supervised by an MDM profile that disables third-party keyboards. Check Settings -> General -> VPN & Device Management. If you see a profile, your administrator has restricted custom keyboards.
Some enterprise app sandboxes disable third-party keyboards inside their own app. The toggle in iOS Settings is still on, but the keyboard refuses to load inside the locked-down app — that is the app talking, not iOS, and there is nothing the extension can do about it.

A specific key does not register

If a single key produces no character or the wrong character:

Confirm the layout is fully visible. Rotate the device into portrait and back if you suspect the keyboard rendered into the wrong frame after a rotation.
Confirm a sticky modifier is not silently armed. Look at the modifier row — Ctrl, Alt, Shift, Cmd, and Fn briefly highlight when armed. Tap an armed modifier to disarm before testing the key alone.
Confirm CapsLock is not on if a letter key is producing the wrong case.

If a special key (Esc, Tab, an arrow, an F-key) appears to send nothing in a specific app, the app is probably consuming the keystroke before the text field sees it. Test the same key inside the host app's sample text field — if it works there, the receiving app is filtering the keystroke. Try inside vmuxPhone, which always passes the bytes through.

Swipe typing keeps committing the wrong word

A few things to check:

Stay on the letter rows. Swipe scoring only looks at letter keys. If your stroke wanders across the number row or punctuation, those keys insert literally and break the word.
Lift cleanly on the last letter. A diagonal lift past the edge of the keyboard sometimes registers an extra letter. Try to lift straight up.
Use the candidate bar. When the right word is your second or third candidate, tap it directly. Each manual pick reinforces the word in your personal frequency table for next time.
Backspace immediately after a wrong commit. A single Backspace within a couple of seconds of the swipe demotes that word in the personal dictionary. The next time you make the same stroke, the demoted word ranks lower.

If swipe is still unreliable for your typing pattern, turn it off in the host app under Enable Swipe Typing. The keyboard reverts to per-tap input.

Layout lag, dropped keystrokes, or visible flicker after rotation

iOS gives keyboard extensions a hard memory ceiling — about 60 MB. The vmux extension fits well under that, but if you have a memory-heavy app foregrounded that the keyboard is layered over, iOS sometimes tears down and reloads the extension under pressure. Symptoms include:

A blank keyboard view for a moment when you tap into a text field.
Keys feeling momentarily sluggish for the first one or two presses.
The candidate bar refusing to show for the first stroke after a relaunch.

Mitigation: close apps you do not need from the app switcher, then come back. The extension's first frame after a relaunch can take ~250 ms; subsequent frames are instant. There is nothing to configure inside the extension itself.

If you see persistent flicker after rotating the device, kill the foreground app from the app switcher and re-open it. iOS occasionally fails to call viewWillLayoutSubviews cleanly across rotation in extensions, and a fresh app launch resolves it.

Switching keyboards mid-word loses my input

This is iOS behavior, not vmux Keyboard. When you tap the globe key while a swipe stroke or composition is in progress, iOS resets the input session — it has no concept of cross-keyboard composition state. Always commit your current input before switching. To avoid losing context, finish your word, tap globe, then continue typing on the next keyboard.

The globe key is missing from the bottom row

iOS hides the globe key when only one keyboard is installed. If Settings -> General -> Keyboard -> Keyboards shows only vmux Keyboard and no other entries, that is the cause. Add a second keyboard (English (US) is the conventional one) and the globe key appears the next time the keyboard reloads. You can hide the globe again by removing the other keyboard.

The keyboard sticks at full height in landscape

The extension targets ~268 pt in landscape on iPhone and ~372 pt in portrait, plus the safe-area inset for the home indicator. If you see the portrait height in landscape:

Force a rotation back to portrait, then back to landscape. iOS sometimes caches the wrong height after a fast rotation.
Close the foreground app and re-open it. The keyboard view reads the host's trait collection on appearance, and a fresh run picks up the correct orientation.

The arrow keys move the cursor in the text field but not in the remote shell

This is by design when you are not in vmuxPhone. The extension always sends the standard xterm escape sequences (ESC [ A, etc) — but the receiving app gets first crack at them. Most iOS text fields handle arrow keys natively (cursor movement) and never forward them. Inside vmuxPhone or any third-party SSH client that exposes a real terminal view, the same bytes go to the remote shell and behave as expected.

I deleted the host app and now my custom keyboard frequencies are gone

The personal frequency table is stored in the host app's UserDefaults. Deleting the app deletes the personal dictionary — there is no iCloud sync of the learned words. After a re-install, the keyboard relearns from scratch. The bundled wordlist of ~20,000 English words is unaffected.

Last resort

Remove vmux Keyboard from Settings -> General -> Keyboard -> Keyboards (Edit -> red minus).
Open the vmux Keyboard host app once.
Re-add the keyboard from Add New Keyboard....
Reboot if it still misbehaves.

If the problem persists, send a description, your iOS version, and the device model to support — see Where to find help for contact details.