Troubleshooting

Start with the menu bar icon. A warning mark means HyperSwitcher has found a problem; open the menu to see it.

A shortcut does nothing

Open Settings → Apps and check both problem filters:

Conflicts means two HyperSwitcher actions have the same key. Give one of them a different key.
Unavailable means macOS refused to register the shortcut, usually because the system or another utility owns it.

The conflict may come from a launcher, window manager, remapping tool, macOS setting, or another app. Change one of the shortcuts, then reopen HyperSwitcher.

Layouts reserve Hyper by itself, Space, Return, Zero, Minus, the physical Equals/Plus key, arrows, and physical Shift. H, J, K, and L are also reserved when Vim navigation is enabled.

If an external tool sends Command + Control + Option + Shift, set General → Hyper key authority to External app and turn on App shortcuts include Shift key. The default layer does not include Shift.

Make sure you are editing the active profile.

The built-in Hyper key does nothing

In Settings → Permissions, allow Accessibility access. If needed, open macOS Privacy & Security → Accessibility, enable HyperSwitcher, then choose Check Again.
Check whether another remapping tool owns Caps Lock or Right Command.
Leave a password field or other secure-input area before testing. macOS intentionally blocks low-level keyboard access there.

If another utility already creates Hyper reliably, let it keep doing so and choose External app in HyperSwitcher.

An app opens, but its windows do not switch or move

Window control needs Accessibility. Enable it under Settings → Permissions, then choose Check Again. With an external Hyper key, basic app activation can still work without access.

If permission is granted, check how HyperSwitcher is choosing windows:

App switching → Follow pointer prefers a window on the display under the pointer; Last used prefers the app’s front or most recent window.
Window switching → Follow pointer limits repeat presses to reachable windows on the pointer display; Cycle all windows ignores the pointer as a display filter.
In Settings → Apps, Ignore when cycling skips minimized windows while a visible one exists; Include when cycling adds them to the rotation.

Move the pointer to the intended display before testing Follow pointer. Windows on another Space or in full screen are best effort; visit the Space, focus the window once, and try again.

If the correct window comes forward but typing stays elsewhere, turn off Advanced → Precise window focusing and try again. The simpler macOS path may raise more of the app’s windows, but it can work better on managed or restricted Macs.

Quick Layout does not appear

Confirm Settings → Layout → Enable Layouts is on.
Grant Accessibility permission.
Focus a normal, movable window.
If you use H, J, K, and L, enable Vim navigation keys.

The hold delay controls only the preview. Layout keys work immediately.

If one app refuses a small region, it may enforce a larger minimum window size. Choose a larger region and try again.

Settings look wrong after a file edit

Open Settings → Advanced and choose Validate File. If the file is valid, choose Reload to read it again and rebuild shortcuts. If it is invalid, restore a known-good copy. Learn how to back up the settings file.

An update check is unavailable

Choose Check for Updates… from the menu bar. It may be briefly unavailable while the updater starts or another check is running. Development builds may not support public update checks.

Send useful details with a bug report

Open Settings → Feedback and describe what happened and what you expected. A reply email and the listed technical details are optional. The license key is never included.

For a hard-to-reproduce problem, use Advanced → Diagnostic Logs → Export… after reproducing it. The export covers roughly the previous 30 minutes and redacts app names, window names, candidate lists, and file paths.

Diagnostic exports are never uploaded automatically. Read the full local-data and telemetry explanation.