Troubleshooting

Troubleshooting

Nothing gets corrected at all

1. Paused? Check the tray menu — Ctrl+Shift+Space (Ctrl+Shift+P on macOS) toggles pause, and it is easy to hit by accident. Since v0.25.2 the state is remembered, so an app you paused last week comes back paused: the icon is grey with a pause mark, the menu says ▶ Resume auto-switch, and the log says auto-switch starts off at startup. [general].paused in config.toml is the same switch.
2. Something didn't come up? A ⚠ …unavailable — Setup… entry at the top of the tray menu says which half: Keyboard hooks means nothing is being read — on Linux that is almost always evdev permissions (Linux-Setup — did you re-login after the setup script?), on macOS a denied permission (macOS-Setup). Layout switching means the reverse: your typing is read, the wrong-layout word is spotted, and there is no way to change the layout, so nothing is touched. Both entries open the Setup pane, which probes this machine and says what is missing.
3. Word too short? Words under 3 letters never trigger a decision by default ([engine] min_word_length).
4. In your editor/terminal? That's the identifier guard doing its job on code-looking tokens — snake_case, camelCase, letter+digit. Use the force-switch hotkey (Ctrl+Shift+Backspace; Ctrl+Shift+F9 on Wayland) — it ignores every filter.

My desktop is not supported

labwc — and with it Budgie's and Xfce's Wayland sessions — and MATE cannot switch the layout. PolterType says so at startup and leaves the word alone. Their X11 sessions work; table in Linux-Setup.

A specific word won't switch

The engine refuses when the typed token already reads as valid for the current layout — a dictionary hit or high plausibility (this is what protects kubectl and surnames). Your options: the force-switch hotkey, or adding the intended word to your wordlist overlay so the dictionary detector has a stronger signal.

Nothing happens while I hold the force-switch key (0.25.1+)

By design, and it is the release that acts, not the press. Nothing can be typed underneath a key you are holding: on X11 the shortcut keeps the keyboard to itself until you let go, and on Wayland the modifier release PolterType sends is discarded — it comes from a virtual keyboard that never pressed the key — so the correction would arrive as Ctrl+H, Ctrl+G, Ctrl+B instead of a word (#44).

So the correction waits for the key to come up. Let go and it happens. Hold for longer than five seconds and it is dropped entirely, leaving the word exactly as you typed it — press again once your hand is off the key.

Corrections come out scrambled when I type fast

The key gate holds your keystrokes back for the length of a correction and types them out behind it. On Linux/evdev it is on by default — except behind an input remapper like keyd, where it stands down. On Windows and macOS it exists and is off by default, because holding adds a noticeable delay after every correction: set POLTERTYPE_HOLD_KEYS=1 in the environment if you type fast enough to hit the race (#7, #8).

The suggestions tooltip never appears

On Linux it needs layer-shell (wlroots, KWin) or X11 — which includes XWayland under GNOME. A Wayland session with neither is the remaining gap (#6); the keyboard accept chord still works there. Windows (0.11.0) and macOS (0.15.0) have their own backends. Apps started before PolterType may need a restart for caret anchoring (AT-SPI activates on launch).

It doesn't start when I log in

Check what the toggle actually installed — on Linux it is a systemd user service:

systemctl --user status dev.opensource.poltertype.service

Inactive, never started on a bare Hyprland/Sway session is the common one: the unit hangs off graphical-session.target, which those sessions do not reach on their own. Linux-Setup has the one-time wiring.

Failed with an exit code is worth a bug report with the journal attached (journalctl --user -u dev.opensource.poltertype.service -b). Starting before the session was ready used to be fatal — up to 0.17.5 a compositor that had not published its environment yet meant a clean exit and no tray icon at all.

Where are the logs?

Tray → Open Logs Folder…. Logs never contain what you type — words are redacted to <N chars> at every level, in every build (since 0.6.3) — so they are safe to attach to a bug report.

Reporting

Use the bug template — it asks for the four things that answer most reports on the spot: version (Settings → About), OS + compositor, the layouts involved, and anything unusual in the input stack (keyd, kanata, Karabiner, AutoHotkey, per-window layout scripts).