kovidgoyal/kitty · error · RemoteControlErrorWithoutTraceback

Unknown action: {ac}

Error message

Unknown action: {ac}

What it means

Raised by kitty's @ action remote-control command when boss.combine() reports that no action was consumed, i.e. the given action name is not a known kitty action or keymap action definition. It signals an unrecognized action string rather than an execution failure, and is surfaced to the remote-control client as a clean error message.

Source

Thrown at kitty/rc/action.py:79

    def message_to_kitty(self, global_opts: RCOptions, opts: 'CLIOptions', args: ArgsType) -> PayloadType:
        return {'action': ' '.join(args), 'self': opts.self, 'match_window': opts.match}

    def response_from_kitty(self, boss: Boss, window: Window | None, payload_get: PayloadGetType) -> ResponseType:
        w = self.windows_for_match_payload(boss, window, payload_get)
        if w:
            window = w[0]
        ac = payload_get('action')
        if not ac:
            raise RemoteControlErrorWithoutTraceback('Must specify an action')

        try:
            consumed = boss.combine(str(ac), window, raise_error=True)
        except (Exception, SystemExit) as e:
            raise RemoteControlErrorWithoutTraceback(str(e))

        if not consumed:
            raise RemoteControlErrorWithoutTraceback(f'Unknown action: {ac}')
        return None


action = Action()

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. List valid actions: kitten @ ls or check the Actions section of the kitty docs / 'kitty +kitten show-key' docs
2. Use the exact action name, e.g. 'kitten @ action scroll_page_down'
3. If referencing a custom compound action, define it first in kitty.conf via map/action_alias and keep the name identical

Example fix

# before
kitten @ action scrolldown

# after
kitten @ action scroll_line_down

try:
    subprocess.run(['kitten', '@', 'action', name], check=True, capture_output=True, text=True)
except subprocess.CalledProcessError as e:
    if 'Unknown action' in e.stderr:
        # name lookup failed; log and fall back to a known action
        log.warning('unknown kitty action %s', name)
    else:
        raise

When it happens

Trigger: Calling 'kitten @ action <name>' where <name> is not a builtin action, an alias, or a defined key mapping action, e.g. 'kitten @ action nosuchthing' or a misnamed compound action 'scroll>page-down'.

Common situations: Action names that changed between kitty versions, typos, using map-definition syntax that requires a matching alias defined in kitty.conf, or passing arguments when none are expected so the whole string fails lookup.

Related errors

• Must specify an action
• The layout {} is unknown or disabled or the name is ambiguou
• This should be run as kitten icat
• This should be run as `kitten notify ...`
• No kitten named {original_kitten_name}

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/d48a8d9295531cdb. Report an issue: GitHub.