Malformed OSC 5522: read request payload is not valid base64

Error message

Malformed OSC 5522: read request payload is not valid base64 encoded UTF-8. Error: {e}

What it means

An OSC 5522 read request's payload (the list of MIME types) failed strict base64 decode or UTF-8 decode; the request is dropped.

Source

Thrown at kitty/clipboard.py:414

            try:
                k, v = record.split('=', 1)
            except Exception:
                log_error('Malformed OSC 5522: metadata is not key=value pairs')
                return
            m[k] = v
        typ = m.get('type', '')
        try:
            m = {k: decode_metadata_value(k, v) for k, v in m.items()}
        except Exception as e:
            log_error(f'Malformed OSC 5522: could not decode a metadata value. Error: {e}')
            if typ in ('wdata', 'walias') and self.in_flight_write_request is not None:
                self.abort_write_request(self.in_flight_write_request, 'EINVAL')
            return
        if typ == 'read':
            try:
                mime_types = tuple(strict_base64_decode(epayload).decode('utf-8').split())
            except Exception as e:
                log_error(f'Malformed OSC 5522: read request payload is not valid base64 encoded UTF-8. Error: {e}')
                return
            rr = ReadRequest(
                is_primary_selection=m.get('loc', '') == 'primary',
                mime_types=mime_types,
                protocol_type=ProtocolType.osc_5522,
                id=sanitize_id(m.get('id', '')),
                human_name=m.get('name', ''),
                password=m.get('pw', ''),
            )
            self.handle_read_request(rr)
        elif typ == 'write':
            self.in_flight_write_request = WriteRequest(
                is_primary_selection=m.get('loc', '') == 'primary',
                protocol_type=ProtocolType.osc_5522,
                id=sanitize_id(m.get('id', '')),
                human_name=m.get('name', ''),
                password=m.get('pw', ''),
            )

View on GitHub (pinned to 6d5d0c4406)

Solutions

Encode the MIME list as base64 UTF-8 before sending
Verify with kitty's clipboard protocol documentation

Example fix

# before
\x1b]5522;type=read\x1b]5522;text/plain\x1b\\
# after
\x1b]5522;type=read\x1b]5522;dGV4dC9wbGFpbg==\x1b\\

Defensive patterns

Strategy: validation

Validate before calling

import base64
def encode_mimes(mimes):
    return base64.b64encode(' '.join(mimes).encode()).decode()

Prevention

Never send raw MIME strings in read requests — always base64 them
Validate payload with strict b64decode before writing to the pty

When it happens

Trigger: typ=read with epayload that is not strict base64 of UTF-8, e.g. raw 'text/plain' sent unencoded.

Common situations: Clients forgetting that the read-request payload must be base64-encoded; protocol experiments.

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

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