{"record":{"id":"f15b8b3c35d48aaf","repo":"kovidgoyal/kitty","slug":"unknown-kitty-remote-control-command-cmd-name","errorCode":null,"errorMessage":"Unknown kitty remote control command: {cmd_name}","messagePattern":"Unknown kitty remote control command: (.+?)","errorType":"exception","errorClass":"KeyError","httpStatus":null,"severity":"error","filePath":"kitty/rc/base.py","lineNumber":469,"sourceCode":"        if command.args.args_count == 0:\n            raise SystemExit(f'Unknown extra argument(s) supplied to {command.name}')\n        raise SystemExit(f'Must specify exactly {command.args.args_count} argument(s) for {command.name}')\n    return opts, items\n\n\ndef display_subcommand_help(func: RemoteCommand) -> None:\n    with suppress(SystemExit):\n        parse_args(['--help'], (func.options_spec or '\\n').format, func.args.spec, func.desc, func.name)\n\n\ndef command_for_name(cmd_name: str) -> RemoteCommand:\n    from importlib import import_module\n\n    cmd_name = cmd_name.replace('-', '_')\n    try:\n        m = import_module(f'kitty.rc.{cmd_name}')\n    except ImportError:\n        raise KeyError(f'Unknown kitty remote control command: {cmd_name}')\n    return cast(RemoteCommand, getattr(m, cmd_name))\n\n\ndef all_command_names() -> frozenset[str]:\n\n    def ok(name: str) -> bool:\n        root, _, ext = name.rpartition('.')\n        return bool(ext in ('py', 'pyc', 'pyo') and root and root not in ('base', '__init__'))\n\n    return frozenset({x.rpartition('.')[0] for x in filter(ok, list_kitty_resources('kitty.rc'))})\n","sourceCodeStart":451,"sourceCodeEnd":480,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/rc/base.py#L451-L480","documentation":"KeyError raised by kitty's remote-control command loader when 'kitty.rc.<name>' cannot be imported — i.e. the requested rc subcommand name is not a known remote-control command. Hyphens are normalized to underscores before the module lookup, so both 'goto-layout' and 'goto_layout' resolve the same way; failure means no such module exists.","triggerScenarios":"Calling 'kitten @ nosuchcmd', command_for_name('foo'), or listing an invalid command in --remote-control-command allowlists/tooling that introspects commands.","commonSituations":"Typos in command names, commands removed/renamed between kitty versions (e.g. older aliases), or custom kittens expected to appear as @ commands without proper registration.","solutions":["List valid commands with 'kitten @' or via all_command_names() / the remote-control docs","Fix the spelling; use hyphens or underscores consistently","If the command was removed in an upgrade, check the changelog for its replacement"],"exampleFix":"# before\nkitten @ goto_layout l1\n\n# after\nkitten @ goto-layout l1   # and verify name via: kitten @ ls of docs; 'kitten @' with no args lists commands","handlingStrategy":"validation","validationCode":"from kitty.rc.base import all_command_names\nname = 'goto-layout'\nif name.replace('_','-') not in {n.replace('_','-') for n in all_command_names()}:\n    raise ValueError(f'{name} is not a kitty rc command')","typeGuard":"def is_rc_command(cmd: str) -> bool:\n    return cmd.replace('-', '_') in {c.replace('-', '_') for c in all_command_names()}","tryCatchPattern":"from kitty.rc.base import command_for_name\ntry:\n    command_for_name(cmd_name)\nexcept KeyError:\n    log.warning('unknown rc command %s; available: %s', cmd_name, sorted(all_command_names()))\n    return None  # skip or prompt user","preventionTips":["Cache all_command_names() and validate user-supplied command names against it","Pin your kitty version in CI so command-name sets don't drift silently"],"tags":["kitty","remote-control","unknown-command","cli"],"backgroundTag":"unknown-command","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}