Troubleshooting

Lumi tries not to fail quietly. A press it cannot carry out puts an alert on screen for two seconds and pins the reason to the row in Shortcuts, so the first place to look is usually the row itself.

The one deliberate exception is a leader menu step with nothing bound to it: the cheatsheet is already on screen listing what that tier answers to, so the menu just closes.

A shortcut does nothing

Work down this list:

1. Which profile is live? A profile is a whole set of automations rather than a filter: the other profile's rows are not hidden from the list, they are not loaded, not registered and cannot fire. The tell is that the row is not in the list at all — the Shortcuts pane draws the live profile's rows and nothing else — so every check below is being made against a row that is not the one you pressed. See Nothing works at all for where Lumi says which profile is live.
2. Is the row switched on? A row that is off claims nothing.
3. Is the Shortcuts master switch on? It releases every binding but Lumi's own.
4. Is it scoped? A row whose Runs in names the applications it works in is silent everywhere else — and one that names the applications it stays out of is silent in exactly those, which is the direction that catches people out. See Scope.
5. Is another app holding the combination? Press Test in the sheet — it claims the combo from macOS and waits to see whether the keypress comes back. (Greyed out for Fn and double-tap triggers: those are never registered with the OS, so there is nothing to test.)
6. Does the action need Accessibility? Send keystroke, media keys, window arranging and cycling all do — see what stops working without it. The press says so rather than failing quietly.
7. Is the target still there? No installed application with bundle id … means the app moved or was removed.

An Fn shortcut in particular

Nothing fires if the Globe key has been remapped — Lumi never sees it. Put it back under System Settings → Keyboard → Keyboard Shortcuts… → Modifier Keys. The Hyper pane says so when it detects this. See Fn as a modifier.

A Run flow shortcut in particular

The press draws the reason and pins it to the row. It is one of: the flow is switched off, the flow was deleted, its Manual trigger was deleted, or the free plan has no room for it. See Flows.

Accessibility says it is granted, but nothing works

Replacing Lumi.app in place can drop the grant. macOS may treat the new copy as a different application. Switch Lumi back on under System Settings → Privacy & Security → Accessibility.

macOS never tells an application when a grant is taken back, so Lumi re-checks whenever its window comes to the front — which is the only moment it can rely on. If the banner is stale, click the window.

Nothing works at all, in every application

Check which profile is live before anything else. It costs nothing to rule out and it is the one cause on this page that is not a fault: a profile is a whole set of automations — shortcuts, leader menus, snippets, Hyper key, double-tap and Fn, all of it — so a profile you have not filled in yet is a Lumi with nothing bound to anything. Create new profile makes an empty one on purpose, and switching to it looks exactly like the app having died.

A switch that works says nothing, because arriving is the whole of it. So a Switch profile shortcut, a leader step, Next profile / Previous profile, or a press in the tray's Profile submenu moves the entire keyboard with no sentence on screen and nothing to go back and read. Three places answer without being asked: the tick in the tray's Profile submenu, the name at the top right of the Settings window and of the Flow Editor, and the name beside Lumi's icon in the menu bar. The last of those is the one that can be missing — it is drawn only once a second profile exists, and only while Show the live profile's name in the menu bar is on in General → Profiles — so the tray and the title bar are the two that always answer.

The rest of this is the event tap. Every one of Lumi's five trigger surfaces — shortcuts, the Hyper key, snippets, double-tap and Fn — reads from one, and two things switch it off wholesale:

• The Accessibility grant is gone. See Accessibility says it is granted, but nothing works above.
• Another application has left secure input on. macOS lets an app capture every keystroke while it holds a password field, and once that is on, nothing reaches Lumi — not the tap, not even a registered hotkey. In an ordinary password field this is invisible and correct. The case worth knowing about is the stuck one: an app turns it on and fails to turn it back off, usually by crashing with a password field focused, or a password manager leaving it set. Every Lumi trigger then stays dead in every application until that process quits.

Lumi checks for the second whenever one of its windows comes to the front — which is the one moment it can be sure no other app's password field has focus, since Lumi has no secure field of its own — and says so in a warning:

Another app is capturing all keyboard input, so Lumi's shortcuts, Hyper key and snippets are paused.

It clears on its own when the field loses focus. If it does not, quit whatever last had a password field open. Lumi deliberately does not name the culprit: the process holding the flag is only reachable through a private call that would be a guess, and a wrong name is worse than none.

A snippet does not expand

1. The master switch at the top of the Snippets pane.
2. The Excluded apps tab — applications listed there switch every snippet off, whatever a snippet says about itself.
3. The snippet's own scope. Only in naming applications you are not in, or Except in naming the one you are. A snippet with nothing named works everywhere. See Where it works.
4. The expand key. A snippet set to fire when you tap the expand key does nothing until one is picked under Snippets → Settings.
5. A pattern that fired too early. ;task(\d+) set to fire as soon as it is typed goes off at ;task1, before the rest is typed. End the pattern with a character you type, or expand on a space, ⇥ or the expand key. See A trigger that is a pattern.
6. A pattern row in the suggestion panel. The accepting key leaves a pattern row alone until the pattern matches what you have typed — there is no rest of a regex for Lumi to supply. Type until it matches, then take it.

A script snippet refused, with an alert

That is the script declining, and it is never silent: the alert says why — it ran over a quarter of a second, it threw, or it returned an array, an object or nothing — and the keystroke it took is handed back, so a Tab is still a Tab. The sheet's Try it box runs the same code, which is the quickest place to see the error with the input in front of you. See A replacement that is a script.

It still does nothing, silently

That is probably the safety net working. Before deleting anything, Lumi reads the text actually in front of your caret and compares it to the trigger — and if it does not match, the snippet is skipped and says nothing. A Vietnamese input method rewrites characters after Lumi has seen them, so the guess and the document genuinely differ; eating the wrong characters is much worse than a missed expansion. Full explanation under Vietnamese and other input methods.

Applications that expose no text at all fall back to backspaces, which is the one path an input method can still throw off.

Log out, Restart or Shut down does nothing

Those three need a second, separate permission, and the press says so:

… needs permission to control loginwindow — allow Lumi under System Settings → Privacy & Security → Automation

Allow it once and it is remembered. See Automation. The other eight system commands ask for nothing.

Cycle windows does nothing

• With one window, or none, nothing happens and nothing is said — macOS's own ⌘` is silent there too, and the press was not refused.
• From Lumi's own window it is refused: Lumi's own windows cannot be cycled — switch to another app first.
• Minimised windows and non-standard windows (sheets, palettes) are skipped on purpose.
• Without Accessibility it is refused out loud.

A leader menu opens with nothing in it

The panel says which of these it is:

A step that presses and closes the menu with no message is a key with nothing bound to it. That silence is deliberate — see the note at the top of this page.

Steps I cannot find any more

Changing a menu row's action, or deleting it, strands the steps inside. Steps whose menu is gone collect under No way in at the bottom of the Shortcuts list, which is the only place they can be seen and so the only place they can be fixed.

A flow will not switch on

• The free plan runs three ways into a flow at once. Switching on a fourth is refused in amber, with the pane that would free a place named. Nothing is written and the switch does not move. See Pro.
• A flow using a node this build does not understand opens read-only and cannot be armed — a flow half of whose steps were silently skipped would do something nobody wrote.
• The Run button in the editor is never capped, so a flow can always be built and tested even when it cannot be armed.

Every setting looks reset

Lumi comes up on Lumi could not read your settings instead of the settings window when the configuration file is not JSON at all — a hand-edit gone wrong, or a truncated write.

A file it cannot parse is neither applied nor overwritten. Losing every shortcut is bad; silently rewriting your settings with defaults is worse — so Lumi leaves it exactly as it found it, keeps a dated copy of it beside the original, and waits.

The screen names the file and has a button that shows it in Finder, so there is nothing to go hunting for. Under it are two ways on:

• Try again, which re-reads the file. That is the answer once you have fixed the JSON in an editor, and it costs nothing to press.
• Start fresh, behind a confirm step, which overwrites it with defaults. It is the only way past this screen that loses anything.

Each profile keeps its own settings, and your licence, snippet history and flows are kept apart from them — so a bad hand-edit to one cannot take the others down.

Some rows are missing, and the rest are fine

That is the opposite case, and nothing was lost. A single value Lumi does not recognise — an action from a newer build, a wire value spelled wrong by hand — does not fail the document any more. The row is lifted out, kept exactly as it was written, and listed in the pane it belongs to under its own heading, so a row that is being held is never mistaken for one that was deleted.

They are written back on every save. Do not re-create them by hand: a row re-created beside one that is still being held is a duplicate the moment the build that understands it comes along.

A field Lumi does not recognise is different — it falls back to its default and is reported, because a setting whose control could never change it would be a stranger failure than a reset one.

Still stuck

Send Feedback… in the menu-bar menu. It carries the build you are running, which is the first thing worth knowing.