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.
2. Hooks failed to start? A ⚠ Setup Guide entry at the top of the tray menu means the keyboard hooks couldn't start — 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).
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.

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.

Corrections come out scrambled when I type fast

The key gate (holding your keystrokes back during a correction) exists on Linux/evdev only, and stands down behind input remappers like keyd — elsewhere a keystroke can still land inside a correction. Windows/macOS equivalents are tracked in #7 and #8.

The suggestions tooltip never appears

It currently renders on Hyprland/Sway (layer-shell) and X11 only — GNOME/KDE Wayland, macOS and Windows have no overlay backend yet (#6). The engine side still works everywhere (the accept chord functions), and apps started before PolterType may need a restart before caret anchoring works (AT-SPI activates on launch).

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).