{"record":{"id":"da8e2830fb1ca7ed","repo":"kovidgoyal/kitty","slug":"remote-control-not-enabled-this-kitten-should-be","errorCode":null,"errorMessage":"Remote control not enabled, this kitten should be run via a map in kitty.conf, not from the command line","messagePattern":"Remote control not enabled, this kitten should be run via a map in kitty\\.conf, not from the command line","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"kittens/tui/handler.py","lineNumber":75,"sourceCode":"\n    def __init__(self, func: Callable[[list[str]], str], allow_remote_control: bool, remote_control_password: bool | str):\n        self.func = func\n        self.allow_remote_control = allow_remote_control\n        self.remote_control_password = remote_control_password\n        self.password = self.to = ''\n        self.rc_fd = -1\n        self.initialized = False\n\n    def initialize(self) -> None:\n        if self.initialized:\n            return\n        self.initialized = True\n        if running_in_kitty():\n            return\n        if self.allow_remote_control:\n            self.to = os.environ.get('KITTY_LISTEN_ON', '')\n            if not self.to:\n                raise ValueError('Remote control not enabled, this kitten should be run via a map in kitty.conf, not from the command line')\n            self.rc_fd = int(self.to.partition(':')[-1])\n            os.set_inheritable(self.rc_fd, False)\n        if (self.remote_control_password or self.remote_control_password == '') and not self.password:\n            import socket\n\n            with socket.fromfd(self.rc_fd, socket.AF_UNIX, socket.SOCK_STREAM) as s:\n                data = s.recv(256)\n            if not data.endswith(b'\\n'):\n                raise Exception(f'The remote control password was invalid: {data!r}')\n            self.password = data.strip().decode()\n\n    def __call__(self, args: list[str]) -> str:\n        self.initialize()\n        return self.func(args)\n\n    def allow_indiscriminate_remote_control(self, enable: bool = True) -> None:\n        if self.rc_fd > -1:\n            if enable:","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/tui/handler.py#L57-L93","documentation":"Raised when a kitten TUI handler runs outside kitty (running_in_kitty() is False) with allow_remote_control=True, but the KITTY_LISTEN_ON environment variable is unset. Without a listen socket the kitten cannot send remote control commands back to a parent kitty instance, which is the only supported way to launch such kittens from the command line.","triggerScenarios":"Running a kitten directly from a plain shell (not via a kitty map or kitten CLI inside kitty) with allow_remote_control=True and no KITTY_LISTEN_ON in the environment; e.g. python -m some_kitten outside a kitty window.","commonSituations":"Testing a kitten in a normal terminal or over SSH; running kitten scripts under cron/CI; kitty.conf missing the map that launches the kitten; kitty started without --listen-on / listen_on config.","solutions":["Run the kitten via a map in kitty.conf (e.g. map f1 launch --type=overlay kitten_name) so kitty provides the socket","Or start kitty with listen_on set (kitty --listen-on unix:/tmp/kitty) and export KITTY_LISTEN_ON for the child","For non-interactive testing, set allow_remote_control=False and stub out remote_control calls"],"exampleFix":"# before\nhandler = ResultHandler(func, allow_remote_control=True)  # fails outside kitty\n# after\n# add to kitty.conf:  map f1 launch --type=overlay mykitten\n# and launch with the map so KITTY_LISTEN_ON is inherited","handlingStrategy":"validation","validationCode":"import os\nfrom kittens.tui.handler import running_in_kitty\ndef can_use_remote_control() -> bool:\n    return running_in_kitty() or bool(os.environ.get('KITTY_LISTEN_ON'))","typeGuard":"def is_launchable_in_kitty(env: dict[str, str]) -> bool:\n    return 'KITTY_LISTEN_ON' in env or 'KITTY_WINDOW_ID' in env","tryCatchPattern":"try:\n    handler.initialize()\nexcept ValueError as e:\n    if 'Remote control not enabled' in str(e):\n        sys.exit('Run this kitten via a map in kitty.conf')\n    raise","preventionTips":["Launch remote-control kittens only via kitty.conf maps","Check KITTY_LISTEN_ON before running in scripts/CI","Start kitty with --listen-on when scripting from outside"],"tags":["kitty","remote-control","environment-variable","kitten"],"backgroundTag":"missing-env-var","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}