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 use the same key on the same shortcut layer, or a saved second-layer assignment is currently dormant. Open the assignment to see the reason.
Unavailable means macOS refused to register the shortcut, usually because the system or another utility owns it.

An unavailable registration may come from a launcher, window manager, remapping tool, macOS setting, or another app. Change the external shortcut or the HyperSwitcher assignment, then reopen HyperSwitcher.

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

With Enable second shortcut layer on, record without Shift for the base layer or with only physical Left Shift for the second. The recorder rejects physical Right Shift or both Shift keys and asks you to use Left Shift only. Right Shift remains the default Quick Layout action key.

If a second-layer assignment says that the layer is off, requires the built-in Hyper key, or is unavailable while app shortcuts include Shift, the assignment is still saved. Restore the required General settings to reactivate it, or record a base-layer replacement. HyperSwitcher does not remap dormant assignments automatically.

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

If the key or its modifiers feel stuck, open the menu bar and choose Reset Hyper Key. The action is available whenever HyperSwitcher provides the Hyper key. It releases HyperSwitcher’s stuck modifier state and restores the built-in key without restarting the app. External Hyper setups and unrelated key mappings stay unchanged.

Follow the message after the reset if HyperSwitcher asks for Accessibility, detects another remapper, cannot find a keyboard, or says the physical key is still held.

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.

A URL action or Terminal command does nothing

Keep HyperSwitcher running before invoking an action. Before a selector-free window, Workspace, or temporary-shortcut action, focus the external app or window you want it to use. When HyperSwitcher is already running, it remembers that external window while LaunchServices activates HyperSwitcher to deliver a URL.

On a cold launch there is no warm target to preserve. If HyperSwitcher says it just launched, leave it running and try the URL again. URL actions can only show a short notice inside HyperSwitcher; CLI commands print a result and return a nonzero exit status when they fail.

For Terminal commands, open Settings → Automation and check the Command Line status. If Terminal reports command not found, add ~/.local/bin to your shell’s PATH, restart Terminal, and try hyperswitcher status.

Use the URL or command copied by the same HyperSwitcher build you intend to control. The regular app uses hyperswitcher and hyperswitcher://; development builds use variant-specific names. Window actions still need Accessibility permission. Use an explicit app selector when an action should always target one app instead of the current external context. See the complete Automation guide.

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.