// troubleshooting guide · hammerspoon

Hammerspoon Hotkeys Stop Working

Status
Workaround available
platforms:
macOS
updated:
November 16, 2026
reports:
3
Method
how we research
Share

RUNBOOK · hammerspoon/hotkeys-stop-working3 FIXES

// quick answer

Hotkeys that stop after a while are most often garbage collected objects or lost permission. Store hotkey objects in persistent variables and reload.

Most likely fix: Keep references alive

How to fix it

// try these in order, the most common fix is first

  1. FIX 1Keep references alive

    1. 01Assign hotkey, timer and watcher objects to a global or a table field
    2. 02Do not leave them as unreferenced locals
    Did this fix it?
  2. FIX 2Reload and check the Console

    1. 01Use the menu bar icon > Reload Config
    2. 02Look for errors such as ipc port is no longer valid
    Did this fix it?
  3. FIX 3Rule out conflicts

    1. 01Quit Karabiner, AeroSpace or similar tools and test
    2. 02Close stray system dialogs
    Did this fix it?

Symptoms

Hotkeys work at first, then stop until Hammerspoon is reloaded.

Why it happens

  • C-01Hotkey object garbage collected
  • C-02Another app or remapper captures the key
  • C-03Permission lost after an update
  • C-04Stray system dialog absorbing events

// this guide also covers

  • hammerspoon hotkey not working
  • hammerspoon hotkeys stopped

Still not working?

If Hammerspoon keeps failing, you're not alone. See every Hammerspoon problem users report or the alternatives people switch to.

Done fighting Hammerspoon? Our small team builds your own Hammerspoon alternative, or any software you need: web, mobile, games, desktop. Price agreed together.

Talk to us

Watch Hammerspoon Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

Other Hammerspoon errors