Troubleshooting permissions
Explains the five permissions Switchboard can ask for, what each one unlocks, and how to fix hotkeys or clicks that stop working.
Keyboard Maestro: Accessibility, Secure Input
macOS makes an app ask before it may watch your keyboard, click in other apps or read the screen. Switchboard asks for the least it can, and only when it first needs a permission.
The permissions belong to Switchboard Engine, the background helper that listens for triggers and runs macros. It is the engine that clicks and listens, so System Settings lists it, not the editor window.
Settings › Permissions shows each one with a status. A permission that isn't on yet has an Allow… button: the engine asks macOS, which adds Switchboard Engine to the list, System Settings opens at the right pane, and a small guide sits on the bottom of its window saying which switch to turn on. It closes by itself once the permission is on, and the row turns green. If you deny the prompt or close it, the row says Not allowed yet after a few seconds, the guide closes, and the row offers Open System Settings… (turn Switchboard Engine on in that list yourself) and Try again.
What each permission unlocks #
| Permission | What it lets Switchboard do | Asked |
|---|---|---|
| Accessibility | Click buttons, read windows and press menu items in other apps. | At first run |
| Input Monitoring | Hear your hotkeys, typed triggers and gestures. | At first run |
| Screen Recording | Find things on screen by their text or picture. | Offered at first run as optional; needed when a step first uses it |
| Automation | Ask other apps to do things, such as AppleScript and Shortcuts. | When a step first needs it |
| Notifications | Tell you when a macro needs you or fails. | When a step first needs it |
| Microphone | Listen when you dictate (Hold to talk). The audio stays on this Mac. | The first time you dictate |
| Full Disk Access | Read every notification other apps post, silenced ones too, for the App notification trigger. The row shows only while a notification trigger exists. | You add Switchboard Engine yourself in System Settings |
Accessibility and Input Monitoring are the two Switchboard needs to be useful at all. The Welcome window asks for them first, and offers Screen Recording as optional. Automation and Notifications wait until a macro needs them.
Which one am I missing? #
| What is wrong | Likely permission |
|---|---|
| A hotkey or typed trigger does nothing, and Activity shows no event at all | Input Monitoring |
| A Click, Set field value or Read field value fails, or a menu step cannot find the menu | Accessibility |
| A click by text or picture fails with a message about Screen Recording | Screen Recording |
| An AppleScript or Shortcuts step says Switchboard isn't allowed to control an app | Automation. Look under Privacy & Security › Automation › Switchboard Engine, and turn the app on |
| You never see failure or approval alerts | Notifications |
| A notification trigger misses notifications a Focus hid, and Permissions says "Reading banners only" | Full Disk Access. Look under Privacy & Security › Full Disk Access, click +, and add Switchboard Engine |
| Holding the dictation key shows "Switchboard Engine isn't allowed to use the microphone" | Microphone. Look under Privacy & Security › Microphone, and turn Switchboard Engine on |
Failing steps say so in words. For example, a missing Accessibility grant fails the step with "Switchboard doesn't have the Accessibility permission".
Fixing a permission #
Open Settings › Permissions and find the row. Click Allow… (or Open System Settings for Automation and Notifications).
Switch Switchboard Engine on. If it isn't in the list, or its switch is on but nothing works, drag the engine's icon from the guide (or from the Welcome) into the list. macOS accepts an app dropped on the list.
When Accessibility and Input Monitoring are both on, Switchboard restarts the engine for you, because a keyboard listener that macOS refused at launch stays refused until the engine starts again. If you changed a switch some other way, click Start Engine or choose Restart Engine from the menu bar.
A switch that is on while nothing works usually means macOS has an old record for a previous copy of the app. Remove Switchboard Engine from the list with the minus button, start the engine again, and allow it afresh.
Secure input #
When you click into a password field, macOS turns on secure input. While it is on, no app may watch the keyboard. Switchboard cannot hear hotkeys or typed triggers until it ends. macOS does this to protect your passwords.
Switchboard shows it in three places:
the engine's menu bar icon, with a line such as "Secure input is on (usually Safari)";
Settings › Permissions › Secure input, which reads On or Off;
Activity, where a held-back event reads "held back because secure input is on".
The name in brackets is a hint. macOS credits secure input to the app in front, which is not always the one that switched it on, so Switchboard says "usually" followed by the app when it is the front app, and "a background app" otherwise. Some terminal and password apps leave secure input on after they lose focus. Quitting the app that actually has it, or locking and unlocking the Mac, clears it.
Only hotkeys and typed triggers are held. Other triggers, such as app launches and time triggers, still fire.
The event tap #
Hotkeys and typed triggers share one keyboard listener, called an event tap. If macOS switches it off because it was slow or because a secure-input app interrupted it, Switchboard turns it back on and writes a line to its log: "event tap was disabled by the system; re-enabled". You do not need to do anything.
If the tap cannot start at all, the engine's trigger status says "event tap refused: Input Monitoring". That means the Input Monitoring permission is missing.
The Fn (Globe) key #
Switchboard can use Fn, which shows as 🌐 on newer Macs, as a modifier in a hotkey, for example fn+space. It sees the Fn flag but never swallows Fn on its own.
macOS may react to the Globe key before Switchboard does: opening the emoji picker, starting dictation, or changing the input source. To use it as a modifier, set the system action to nothing in System Settings › Keyboard, in the option labelled "Press 🌐 key to": Do Nothing.
After a macOS update #
A major macOS update can reset privacy grants or leave an old record. If hotkeys or clicks stop working after an update:
Check Settings › Permissions.
Open each pane in System Settings and confirm Switchboard Engine is on.
If a switch is on but nothing works, remove the entry and let the engine ask again.
Check Activity for the reason. Debugging explains Not Fired.
When it still does not work #
Is the engine running? Settings › Permissions says so at the top, and has a Start Engine button.
Is Switchboard paused? A paused Switchboard holds every trigger. Activity shows "Switchboard was paused".
Another app may be using the same hotkey. Activity shows a conflict if two macros share keys; macOS and other apps can still claim a key first.