kovidgoyal/kitty · error · TimeoutError

Timed out while waiting to read cmd response

Error message

Timed out while waiting to read cmd response

What it means

The remote-control client reads the response from kitty's socket; if no DCS-framed response arrives within the timeout, TimeoutError is raised. Typically kitty never answered (busy, hung, or the command was swallowed).

Source

Thrown at kitty/remote_control.py:363

                out.write(data)
            else:
                for chunk in data:
                    if isinstance(chunk, str):
                        chunk = chunk.encode('utf-8')
                    out.write(chunk)
                    out.flush()
        self.socket.shutdown(socket.SHUT_WR)

    def simple_recv(self, timeout: float) -> bytes:
        dcs = re.compile(rb'\x1bP@kitty-cmd([^\x1b]+)\x1b\\')
        self.socket.settimeout(timeout)
        st = monotonic()
        with self.socket.makefile('rb') as src:
            data = src.read()
        m = dcs.search(data)
        if m is None:
            if monotonic() - st > timeout:
                raise TimeoutError('Timed out while waiting to read cmd response')
            raise SocketClosed('Remote control connection was closed by kitty without any response being received')
        return bytes(m.group(1))


class RCIO(TTYIO):
    def simple_recv(self, timeout: float) -> bytes:
        ans: list[bytes] = []
        read_command_response(self.tty_fd, timeout, ans)
        return b''.join(ans)


def do_io(to: str | None, original_cmd: dict[str, Any], no_response: bool, response_timeout: float, encrypter: 'CommandEncrypter') -> dict[str, Any]:
    payload = original_cmd.get('payload')
    if not isinstance(payload, GeneratorType):
        send_data: bytes | Iterator[bytes] = encode_send(encrypter(original_cmd))
    else:

        def send_generator() -> Iterator[bytes]:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Retry the command (transient load is common)
2. Increase the timeout if the API exposes one
3. Verify kitty is responsive and the remote-control socket path is correct
4. Check for kitty version mismatches between client and server

import subprocess
r = subprocess.run(['pgrep','-x','kitty']); assert r.returncode==0, 'kitty not running'

for attempt in range(3):
    try: run_cmd()
    except TimeoutError: sleep(1)
    else: break

When it happens

Trigger: @kitten remote-control command over a slow/hung transport (SSH, or kitty busy rendering) where monotonic() - start exceeds the timeout before any data with a DCS match.

Common situations: Remote control over SSH to a loaded machine, kitty frozen, or kitty version mismatch where responses aren't framed as expected.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Timed out waiting for a response from kitty
• This should be run as kitten icat
• This should be run as `kitten notify ...`
• Remote control not enabled, this kitten should be run via a
• The remote control password was invalid: {data!r}

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