Chrome extension keyboard shortcut not working: fixing commands in MV3
7 min readModerok team
Why chrome.commands.onCommand never fires in a Manifest V3 extension, the manifest and listener fix, and the cases that fail silently.
If your Chrome extension keyboard shortcut is not working, the usual cause is that the command is a reserved action command, which Chrome never dispatches to onCommand, or that the listener is not registered at the top level of the service worker. Give the command your own name, add a description, and register the handler in the global scope:
{
"manifest_version": 3,
"name": "My Extension",
"version": "1.0.0",
"background": { "service_worker": "background.js", "type": "module" },
"commands": {
"toggle-feature": {
"suggested_key": { "default": "Ctrl+Shift+Y", "mac": "Command+Shift+Y" },
"description": "Toggle the feature on the current tab"
}
}
}
// background.js, top level, not inside any callback
chrome.commands.onCommand.addListener((command, tab) => {
if (command === "toggle-feature") {
console.log("fired on tab", tab?.id);
}
});
The commands key is the only manifest entry the API needs. Chrome's reference lists "commands" under "The following keys must be declared in the manifest to use this API" (Chrome for Developers), with no permission to declare alongside it. Its samples now read browser.commands, because the page notes that "Chrome now supports the standardized browser.* namespace (available from Chrome 148)".
Why your Chrome extension keyboard shortcut is not working
Four failures account for almost all of these reports, and they look identical from the keyboard.
The command name is reserved. _execute_action (MV3), _execute_browser_action and _execute_page_action (MV2) trigger the action itself. Chrome's page says these "don't dispatch command.onCommand events like standard commands", and its own example carries the comment // This callback WILL NOT be called for "_execute_action" (Chrome for Developers). To run code when that shortcut is pressed, Chrome suggests listening for DOMContentLoaded inside the popup. With no popup declared, the shortcut reaches chrome.action.onClicked instead, the pairing described in tracking which features people use.
The command name starts with an underscore but is not one of those three. Chromium's commands handler files a named command only when command_name[0] != '_', under the comment // Commands w/underscore are reserved. (commands_handler.cc). A command called _my_toggle loads without complaint and never fires.
_execute_action is declared but the manifest has no action key. The same handler stores the binding only when the matching action key exists, and otherwise adds an install warning: "The action commands in the manifest do not match the manifest's action type and were ignored." (manifest_constants.h). A warning is not an error, so the extension loads and the shortcut does nothing. Chrome's action-command example declares "action": {} next to the command for this reason.
The listener is nested. Chrome's events guide states that "Event handlers in service workers need to be declared in the global scope, meaning they should be at the top level of the script and not be nested inside functions. This ensures that they are registered synchronously on initial script execution" (Chrome for Developers). A handler added inside a chrome.storage.local.get callback or after an await works while you watch the worker console and stops once the worker has shut down: the keypress wakes a fresh worker that has not reached your addListener call yet. The lifecycle page notes that "if the service worker has gone dormant, an incoming event will revive them" (Chrome for Developers), and the revived worker gets the event only if the handler was registered during that initial evaluation. This is the ordering rule behind chrome.storage.onChanged not firing.
The manifest errors that stop the extension loading
A malformed commands block fails the parse, so the extension never installs. These strings come straight from Chromium's manifest parser, with * filled in at runtime:
Invalid value for 'commands[*].description'.Chromium'sCommand::Parsereturns this wheneverdescriptionis missing or empty on a non-action command, and the docs confirm "Descriptions are required for standard commands, but are ignored for Action commands".Too many shortcuts specified for 'commands': The maximum is 4.The docs put it as "An extension can have many commands, but may specify at most four suggested keyboard shortcuts." Commands with nosuggested_keydo not count, and neither do media keys, which the handler skips because "media keys aren't registered exclusively they should not count towards the max of four shortcuts per extension".Unknown platform for 'command[*]': *. Valid values are: 'windows', 'mac' 'chromeos', 'linux' and 'default'.No other platform keys are accepted insidesuggested_key.Could not find key specification for 'command[*].*': Either specify a key for '*', or specify a default key.List only"linux"and a Windows install has nothing to fall back on.Commandoutside the"mac"section fails with "Command key is not supported. Note: Ctrl means Command on Mac", andOptionwith "Option key is not supported."
The combination itself has to satisfy four rules: "Extension command shortcuts must include either Ctrl or Alt", "Modifiers cannot be used in combination with Media Keys", Ctrl+Alt is rejected because "Key combinations that involve Ctrl+Alt are not permitted in order to avoid conflicts with the AltGr key", and casing is literal: "Key definitions are case sensitive. Attempting to load an extension with an incorrectly cased key will result in a manifest parse error at installation time." Ctrl+Shift+y is not Ctrl+Shift+Y. The supported list is A to Z, 0 to 9, Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete, the four arrow keys and the four media keys. Function keys are not on it.
Check what actually got bound
A manifest that parses is not a shortcut that exists. Chrome's docs are blunt about collisions: "If an extension attempts to register a shortcut that is already used by another extension, the second extension's shortcut won't register as expected." Read the real state with chrome.commands.getAll(), which returns each command "and their shortcut (if active)":
chrome.runtime.onInstalled.addListener(async ({ reason }) => {
if (reason !== chrome.runtime.OnInstalledReason.INSTALL) return;
const commands = await chrome.commands.getAll();
const unbound = commands.filter((c) => !c.shortcut).map((c) => c.name);
if (unbound.length) {
// Tell the user to assign them at chrome://extensions/shortcuts
}
});
Chrome's sample gates this on first install for the reason its own comment gives: after installation the user may have intentionally unassigned a command. The promise form of getAll is Chrome 96 and later, and "Before Chrome 110, this command did not return _execute_action."
What still breaks after the fix
The shortcut is the user's, not yours. "The user can manually add more shortcuts from the chrome://extensions/shortcuts dialog", and that page is also where they change or clear what you suggested, so treat every binding as advisory.
Some keys you cannot win: "Certain operating system and Chrome shortcuts (e.g. window management) always take priority over Extension command shortcuts and cannot be overridden." On macOS, "Ctrl is automatically converted into Command", so a "default" of Ctrl+Shift+Y is Command+Shift+Y there. For the real Control key, write MacCtrl in the "mac" entry only, because "Using MacCtrl in the combination for another platform will cause a validation error and prevent the extension from being installed."
Marking a command "global": true lets it fire while Chrome is unfocused, but "Keyboard shortcut suggestions for global commands are limited to Ctrl+Shift+[0..9]", and "ChromeOS does not support global commands."
If you migrated from MV2, MDN records that a user's changed _execute_browser_action shortcut "is automatically carried over to the _execute_action command when the extension migrates from Manifest V2 to V3. This was implemented in Chrome 111 and Firefox 127" (MDN).
Firefox differences
Firefox implements the same manifest key, and MDN notes the API "is based on Chromium's chrome.commands API", but the edges differ.
Firefox lets you change bindings at runtime: MDN lists commands.update(), commands.reset() and commands.openShortcutSettings() plus a commands.onChanged event, and states that "In Chrome, extensions can't programmatically update shortcut keys. Users can change shortcuts at chrome://extensions/shortcuts, which can be opened using tabs.create()." Firefox users manage theirs through Manage Extension Shortcuts at about:addons.
The accepted keys differ too. Firefox combinations "must consist of 2 or 3 keys", and its list includes the function keys F1 to F12, which Chrome's does not; from Firefox 135 users can assign F13 to F19 themselves, while "Your extension can't assign these keys from the manifest file." MDN's suggested_key also accepts "android" and "ios", which Chrome rejects as unknown platforms. Firefox keeps _execute_page_action in MV3 and supports _execute_sidebar_action, neither of which exists in Chrome MV3. Its collision warning is worth memorising: "You can define it, but your event handler will not be called when the user presses the key combination." A Firefox MV3 background is an event page rather than a service worker (event pages vs service workers), though the top-level registration discipline is identical.
Knowing whether anyone presses it
Once the handler fires locally you still do not know whether users ever found the shortcut, and a command nobody triggers is an argument for dropping it. The command name arrives as a plain string, the flat property shape an event wants: Moderok.track("shortcut_used", { command }) inside the onCommand handler gives a count per command, and a popup-opening shortcut has to be counted from the popup, since reserved action commands never reach onCommand. The events guide covers the naming and property rules.