kovidgoyal/kitty · error

Failed to parse JSON payload of remote command, ignoring it

Error message

Failed to parse JSON payload of remote command, ignoring it

What it means

An incoming remote-control command (over the socket or via escape sequence) had a payload that is not valid JSON, so parse_cmd discards it. Usually the result of an encrypted payload being sent without decryption or a truncated/garbled message.

Source

Thrown at kitty/remote_control.py:52

active_async_requests: dict[str, float] = {}
active_streams: dict[str, str] = {}
T = TypeVar('T')
if TYPE_CHECKING:
    from .window import Window


def encode_response_for_peer(response: Any) -> bytes:
    return b'\x1bP@kitty-cmd' + json.dumps(response).encode('utf-8') + b'\x1b\\'


def parse_cmd(serialized_cmd: memoryview, encryption_key: EllipticCurveKey) -> dict[str, Any]:
    # See https://github.com/python/cpython/issues/74379 for why we cant use
    # memoryview directly :((
    try:
        pcmd = json.loads(bytes(serialized_cmd))
    except Exception:
        log_error('Failed to parse JSON payload of remote command, ignoring it')
        return {}
    if not isinstance(pcmd, dict) or 'version' not in pcmd:
        log_error('JSON payload of remote command is invalid, must be an object with a version field')
        return {}
    pcmd.pop('password', None)
    if 'encrypted' in pcmd:
        if pcmd.get('enc_proto', '1') != RC_ENCRYPTION_PROTOCOL_VERSION:
            log_error(f'Ignoring encrypted rc command with unsupported protocol: {pcmd.get("enc_proto")}')
            return {}
        pubkey = pcmd.get('pubkey', '')
        if not pubkey:
            log_error('Ignoring encrypted rc command without a public key')
        d = AES256GCMDecrypt(encryption_key.derive_secret(base64.b85decode(pubkey)), base64.b85decode(pcmd['iv']), base64.b85decode(pcmd['tag']))
        data = d.add_data_to_be_decrypted(base64.b85decode(pcmd['encrypted']), True)
        pcmd = json.loads(data)
        if not isinstance(pcmd, dict) or 'version' not in pcmd:
            return {}
        delta = time_ns() - pcmd.pop('timestamp')

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Verify the client and server are the same kitty version
2. Ensure allow_remote_control is enabled and the client is actually speaking the kitty RC protocol
3. If using encryption, confirm the payload is wrapped correctly (enc_proto/pubkey fields) rather than raw plaintext

import json
def send_rc(sock, payload: dict):
    data = json.dumps(payload).encode()
    sock.sendall(data)  # never send partial/arbitrary bytes

def is_valid_rc_payload(raw: bytes) -> bool:
    try:
        d = json.loads(raw)
    except Exception:
        return False
    return isinstance(d, dict) and 'version' in d

When it happens

Trigger: @kitty/remotely-control or socket clients sending non-JSON bytes; the raw serialized_cmd fails json.loads in parse_cmd, called from _handle_remote_command.

Common situations: Version mismatch between kitten CLI and kitty daemon, a proxy/tool mangling the socket stream, or stray data sent to the remote-control socket.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• The remote control password was invalid: {data!r}
• Invalid response received from kitty, unmarshalling error: %
• 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

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