Skip to content
Documentation
Troubleshooting

Troubleshooting

When a shortcut suddenly stops working or behaves in a way you didn’t expect, this is the place to start. Most keyboard trouble comes from one of three things: another app is fighting Uncapped for the same key, something overwrote the remapping that powers the Hyper Key, or Caps Lock is simply doing its new job instead of its old one. Each section below describes a symptom in plain terms and walks through the fix.

Uncapped also keeps an eye out for the first two of these on its own. When it spots trouble it shows a small red warning dot next to the Settings item in the sidebar, and the Settings screen has two sections — Possibly Interfering Apps and Keyboard Remapping Conflicts — that name the likely culprit. The fixes here pair with those two sections.

The Hyper Key stopped working

You press your Hyper Key (Caps Lock by default) and nothing happens — even though Uncapped still shows it as enabled. This almost always means another keyboard tool has quietly taken over your Caps Lock key.

To make the Hyper Key work, Uncapped reassigns Caps Lock deep in the system so the rest of macOS sees it as a spare key (F18) it can build shortcuts on. If you run a second tool that also remaps Caps Lock — another Hyper Key app, for instance — whichever one acted last wins, and Uncapped’s mapping gets overwritten. Everything in Uncapped still looks correct, which is what makes this so confusing.

There are a few variations, but they all have the same feel — the key looks set up but does nothing:

  • Another app has pointed your Caps Lock (or whichever trigger you chose) at a different key, so Uncapped’s mapping never takes effect.
  • Uncapped’s own mapping has been overwritten and is now missing.
  • Another tool wrote a mapping as it quit that silently overrides Uncapped’s, leaving the key dead even though that other app is no longer running.

How to fix it:

  1. Open the Settings screen and look at the Keyboard Remapping Conflicts section. If something else is remapping your key, Uncapped flags it here with a warning.
  2. Find the other keyboard tool and either quit it or turn off its Caps Lock remapping. The Possibly Interfering Apps section just above often names the responsible app.
  3. Click Rescan in that section to re-check. A common culprit is another “Hyper Key” utility — popular ones include Superkey and Raycast.
  4. If the key is still dead after the other tool is gone, toggle the Hyper Key off and back on on the Hyper Key screen (this re-applies Uncapped’s mapping), or simply restart Uncapped.
For the technically curious. Uncapped powers the Hyper Key by mapping Caps Lock → F18 through the system’s HID UserKeyMapping property. It writes this mapping globally with hidutil; some other tools (Superkey, Raycast) write theirs per-device using IOKit, which a global query doesn’t see — so Uncapped reads back both the global mapping and each connected keyboard’s per-device mapping, then compares what’s actually live against what it expects (Caps Lock → F18 while the Hyper Key is on, nothing while it’s off). Anything else mapping the same key — including a “key → itself” mapping some tools leave behind on quit — is reported as a conflict.

If your trouble is specifically that the Hyper Key keeps switching off whenever you quit another keyboard app, Uncapped can re-apply itself automatically — see Hyper Key ▸ Recovery.

A shortcut fires twice or behaves oddly

A shortcut works most of the time, or does something slightly wrong — fires twice, inserts stray characters, or triggers a different action than you set up. When a shortcut is inconsistent rather than completely dead, the usual cause is another app reading the same keystroke before Uncapped does.

Uncapped isn’t the only kind of app that listens to your keyboard. Launchers, text expanders, and automation tools all watch your keystrokes too, and when two apps both react to the same press, they can step on each other. Common examples are Raycast, Alfred, Keyboard Maestro, and text-expansion utilities.

How to fix it:

  1. Open the Settings screen and check the Possibly Interfering Apps section. Uncapped lists every other app it can see intercepting the keyboard right now, each with its icon and name.
  2. Quit one of the listed apps — start with whichever one you suspect owns the misbehaving shortcut — and test again.
  3. Click Rescan after quitting an app to confirm it’s no longer in the list.
  4. If you need to keep that app running, change its shortcut (or Uncapped’s) so the two no longer share the same key.
For the technically curious. Uncapped keeps no hard-coded blocklist of apps. It asks macOS for the list of active keyboard event taps — the mechanism apps use to listen in on input — and resolves the ones handling key events back to the apps that created them, filtering out its own taps and Apple’s built-in services. Because it’s based on actual behavior rather than a list of names, it even catches command-line tools and daemons (such as skhd or yabai) that have no normal app window.

Caps Lock no longer types capitals

You press Caps Lock expecting capital letters and nothing happens. This isn’t a bug — it’s the Hyper Key doing exactly what it’s meant to. When the Hyper Key is on, your Caps Lock key becomes the Hyper Key, so it no longer toggles capitals the way it used to.

If you’d like capitals back, you have three options, all on the Hyper Key screen:

  • Keep both. Turn on Enable Quick tap and set On tap to Toggle Caps Lock (its default). A quick tap of the key then toggles capitals as normal, while holding it still works as the Hyper Key. See Hyper Key ▸ Quick Tap.
  • Hold for capitals. Turn on Long press toggles Caps Lock so that holding the key down toggles real Caps Lock, while a quick tap runs your chosen tap action. See Hyper Key ▸ Long Press.
  • Give Caps Lock back entirely. Change the Trigger key to a different key (such as Right Command) so Caps Lock returns to normal, or turn the Hyper Key off altogether. See Hyper Key ▸ Choosing your trigger key.
SettingsFAQ