// troubleshooting guide · aerospace

AeroSpace Keybindings Not Working

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

RUNBOOK · aerospace/keybindings-not-working4 FIXES

// quick answer

AeroSpace hotkeys usually fail because another app grabs the same shortcut, the config didn't load, or Accessibility permission was lost. Check for conflicts with skhd, Karabiner or Raycast, then reload the config.

Most likely fix: Remove hotkey conflicts

How to fix it

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

  1. FIX 1Remove hotkey conflicts

    1. 01Quit skhd, Karabiner-Elements, Raycast and other hotkey tools
    2. 02Test the AeroSpace binding again
    3. 03Rebind the conflicting shortcut in one of the apps
    Did this fix it?
  2. FIX 2Keep only one config file

    1. 01Check ~/.aerospace.toml and ~/.config/aerospace/aerospace.toml
    2. 02Delete or rename one; AeroSpace reports an error when both exist
    Did this fix it?
  3. FIX 3Reload and check the config

    1. 01Run aerospace reload-config in Terminal and read any errors
    2. 02After v0.21.0, quote unusual binding right-hand sides
    3. 03Set auto-reload-config = true so saves apply automatically
    Did this fix it?
  4. FIX 4Re-grant Accessibility

    1. 01System Settings > Privacy & Security > Accessibility
    2. 02Toggle AeroSpace off and on, then restart it
    Did this fix it?

SANDBOX · aerospace RUNS IN YOUR BROWSER

Try it: a launcher with snippets and clipboard history

A hands-on AeroSpace-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.

Symptoms

Some or all alt-based shortcuts do nothing, or they type special characters instead of switching workspaces.

Why it happens

  • C-01Another global key listener (skhd, Karabiner-Elements, Raycast) uses the same keys
  • C-02Two config files exist (~/.aerospace.toml and ~/.config/aerospace/aerospace.toml)
  • C-03Config syntax broken by the v0.21.0 binding parser rewrite
  • C-04Accessibility permission dropped

// this guide also covers

  • aerospace shortcuts not working
  • aerospace alt key not working
  • aerospace hotkeys stopped working

Still not working?

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

Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.

Talk to us

Watch AeroSpace 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 AeroSpace errors