octobercms/october · error · Error

command option is not set for toolbar button

Error message

command option is not set for toolbar button

What it means

The backend document toolbar-button Vue component throws in its click handler when a plain (non-dropdown, non-menu) button has no `command` setting — the click would have nothing to emit. Only dropdown buttons, link buttons (settings.href), and menu buttons are allowed to omit `command`. Hotkey-triggered activation shares this code path, so keyboard shortcuts hit the same check.

Source

Thrown at modules/backend/vuecomponents/document/assets/js/toolbar-button.js:131

                ev.preventDefault();
                ev.stopPropagation();
                return false;
            }

            if (this.settings.href) {
                if (isHotkey) {
                    window.open(this.settings.href, this.settings.target ? this.settings.target : '_self');
                }

                return;
            }

            ev.preventDefault();
            ev.stopPropagation();

            if (this.settings.type != 'dropdown' && !isMenuButton) {
                if (!this.settings.command) {
                    throw new Error('command option is not set for toolbar button');
                }

                this.$emit('command', this.settings.command, isHotkey, ev, this.$el, this.settings.customData);
                return false;
            }

            if (this.settings.emitCommandBeforeMenu) {
                this.$emit('command', this.settings.emitCommandBeforeMenu, isHotkey, ev, this.$el, this.settings.customData);
            }

            this.$refs.menu.showMenu(this.settings.type == 'dropdown' ? this.$refs.button : this.$refs.menuButton);
            return false;
        },

        onMenuClosedWithEsc: function onMenuClosedWithEsc() {
            var that = this;
            Vue.nextTick(function () {
                that.$refs.button.focus();

View on GitHub (pinned to b608633a7e)

Solutions

1. Add a command to the button settings: {title:'Save', type:'button', command:'save'}.
2. If the button should open a menu, set type:'dropdown' and provide items; if it navigates, set href (and optional target).
3. Make sure the parent component listens to @command to handle the emitted event.

Example fix

// before
this.addToolbarButton({
    title: 'Save',
    type: 'button'
});

// after
this.addToolbarButton({
    title: 'Save',
    type: 'button',
    command: 'save'
});

function toolbarButtonIsActionable(settings) {
    if (settings.type === 'dropdown' || (settings.items && settings.items.length)) return true;
    if (settings.href) return true;
    return typeof settings.command === 'string' && settings.command.length > 0;
}

// when building the toolbar
if (!toolbarButtonIsActionable(button)) {
    console.error('Toolbar button needs a command, href or menu:', button);
}

When it happens

Trigger: A toolbar button defined with the default type and no command is clicked, or its hotkey fires: settings = {title:'Save', type:'button'} without a `command` key reaches the $emit branch and throws.

Common situations: New toolbar buttons added to a backend document UI where the developer forgot the command; button settings built dynamically and the command key dropped by a conditional; renaming `command` during refactors.

Related errors

• command option is not set for menu item
• Radio button and checkbox dropdown menu items cannot have ic
• getDynamicOptionsExtraData must return an object
• Inspector title is a required string
• Inspector Object must be an object

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/9e8a7e44e5f18e97. Report an issue: GitHub.