kovidgoyal/kitty · error

Timed out waiting for a response from kitty

Error message

Timed out waiting for a response from kitty

What it means

kitty @ sent a remote control command and heard nothing back before the response timeout elapsed. After cancelling the async request it reports this timeout, meaning kitty never answered (busy, socket dead, or command genuinely long-running).

Source

Thrown at tools/cmd/at/main.go:234

			self.chunks_done = true
		}
		return self.serializer(self.rc)
	}
	self.chunks_done = true
	return self.serializer(self.rc)
}

func get_response(do_io func(io_data *rc_io_data) ([]byte, error), io_data *rc_io_data) (ans *Response, err error) {
	serialized_response, err := do_io(io_data)
	if err != nil {
		if errors.Is(err, os.ErrDeadlineExceeded) && io_data.rc.Async != "" {
			io_data.rc.Payload = nil
			io_data.rc.CancelAsync = true
			io_data.multiple_payload_generator = nil
			io_data.rc.NoResponse = true
			io_data.chunks_done = false
			_, _ = do_io(io_data)
			err = fmt.Errorf("Timed out waiting for a response from kitty")
		}
		return nil, err
	}
	if len(serialized_response) == 0 {
		if io_data.rc.NoResponse {
			res := Response{Ok: true}
			ans = &res
			return
		}
		err = fmt.Errorf("Received empty response from kitty")
		return
	}
	var response Response
	err = json.Unmarshal(serialized_response, &response)
	if err != nil {
		err = fmt.Errorf("Invalid response received from kitty, unmarshalling error: %w", err)
		return
	}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Increase the timeout with --response-timeout (seconds) for slow commands like get-screenshot or launch
2. Verify kitty is responsive and remote control is enabled (--allow-remote-control)
3. If over ssh, check the connection is alive and the env is forwarded
4. Re-run the command; transient stalls during heavy GPU load can cause this

Example fix

# before
kitty @ get-screenshot
# after
kitty @ --response-timeout=60 get-screenshot

kitty @ --response-timeout=60 <cmd>

if err := send_rc_command(...); err != nil && strings.Contains(err.Error(), "Timed out") { time.Sleep(time.Second); /* retry once */ }

When it happens

Trigger: send_rc_command waits on get_response; if the response channel times out (default timeout reached, or a timeout set via --response-timeout), the error is raised and the request is cancelled.

Common situations: Very slow commands (e.g. getting a large screenshot or launching apps) exceeding the default 10s timeout, kitty frozen/busy, the remote control socket connection silently dropped, or network latency when forwarding over ssh.

Understand the failure class

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

Related errors

• Timed out while waiting to read cmd response
• 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/33d0afeaa9201d1e. Report an issue: GitHub.