Troubleshooting

My new keybind doesn’t fire

Foundry registers keybindings during startup. A binding created or changed mid-session isn’t active until you reload the page. The Keybind field shows the notification “Reload page to apply changes”.

The combination I want is already taken

Two paths:

• Another Macro Keybinds binding owns it. Assigning the same combination to a new macro removes the older binding without a prompt. The older macro is left unbound.
• A core or other-module binding owns it. Foundry surfaces the conflict in Controls Configuration. Clear or remap the conflicting action from there, then reload.

I renamed a macro and the binding shows the old name

The stored name updates when you rename the macro from its sheet. The updateMacro hook syncs it. If you renamed via a script or a flow that bypasses the macro sheet, open and re-save the macro to refresh the stored name.

I deleted a macro but its binding entry is still there

Stored bindings for deleted macros are harmless. They are still registered as keybinding actions on reload, but they no-op when fired because the action looks up the macro and finds nothing. The stale entries are purged automatically the next time you open Controls Configuration. When its render hook fires, Macro Keybinds rebuilds its store and keeps only macros that still exist.

Edits in Controls Configuration don’t stick

They do, but the sync happens when the Controls Configuration window renders. When its render hook fires, Macro Keybinds reads each registered macro action back out of Foundry and rewrites its own store to match. If a binding is missing afterward, check that the macro itself still exists, then reload.

Number keys still trigger the hotbar after enabling “Disable Default Hotbar Numbers”

The setting is marked requiresReload. Reload the world after toggling it. The setting clears the core executeMacro0-executeMacro9 actions when you toggle it, but the underlying input handlers refresh only on reload.

A modifier-only combination won’t record

The field rejects bindings that are nothing but modifiers. Hold the modifiers, then press a non-modifier key.