kovidgoyal/kitty · error · TypeError

Invalid encoding for send-text data: {encoding}

Error message

Invalid encoding for send-text data: {encoding}

What it means

send-text validates the --encoding argument against the allowed set (text/base64/kitty-key/session); anything else raises TypeError.

Source

Thrown at kitty/rc/send_text.py:222

        sid = payload_get('session_id', '')
        windows = self.windows_for_payload(boss, window, payload_get, window_match_name='match')
        pdata: str = payload_get('data')
        encoding, _, q = pdata.partition(':')
        session = ''
        if encoding == 'text':
            data: bytes | WindowSystemKeyEvent = q.encode('utf-8')
        elif encoding == 'base64':
            data = base64.standard_b64decode(q)
        elif encoding == 'kitty-key':
            bdata = base64.standard_b64decode(q)
            candidate = decode_key_event_as_window_system_key(bdata.decode('ascii'))
            if candidate is None:
                raise ValueError(f'Could not decode window system key: {q}')
            data = candidate
        elif encoding == 'session':
            session = q
        else:
            raise TypeError(f'Invalid encoding for send-text data: {encoding}')
        exclude_active = payload_get('exclude_active')
        actual_windows = (w for w in windows if w is not None and (not exclude_active or w is not boss.active_window))

        def create_or_update_session() -> Session:
            s = sessions_map.setdefault(sid, Session(sid))
            return s

        if session == 'end':
            s = create_or_update_session()
            for w in actual_windows:
                w.screen.render_unfocused_cursor = False
                s.window_ids.discard(w.id)
            ClearSession(sid)()
        elif session == 'start':
            s = create_or_update_session()
            if window is not None:

                def is_ok(x: Any) -> bool:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use one of the supported encodings: text, base64, kitty-key, or session
2. Check kitty version documentation for the current encoding list

ENCODINGS = {'text','base64','kitty-key','session'}
assert encoding in ENCODINGS, f'unsupported encoding: {encoding}'

def is_valid_encoding(e: str) -> bool: return e in {'text','base64','kitty-key','session'}

When it happens

Trigger: Passing an encoding string other than 'text', 'base64', 'kitty-key', or 'session' to the send-text remote command payload.

Common situations: Typos in encoding names, or scripts written against an older/newer kitty where the encoding set differs.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown type_of_input: {type_of_input}
• Unknown keys in multicell_command:
• The value {x} is not a known choice
• The value {val} is not a valid choice for progress_bar
• The value {val} is not a valid choice for scrollbar

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