kovidgoyal/kitty · error · Exception

Unknown keys in multicell_command:

Error message

Unknown keys in multicell_command: 

What it means

client.multicell_command builds an OSC 50-style text-size escape sequence and raises a plain Exception when the passed command dict contains keys it does not recognize, to catch typos or unsupported options early.

Source

Thrown at kitty/client.py:322

def multicell_command(payload: str) -> None:
    c = json.loads(payload)
    text = c.pop('', '')
    m = ''
    if (w := c.pop('width', None)) is not None and w > 0:
        m += f'w={w}:'
    if (s := c.pop('scale', None)) is not None and s > 1:
        m += f's={s}:'
    if (n := c.pop('subscale_n', None)) is not None and n > 0:
        m += f'n={n}:'
    if (d := c.pop('subscale_d', None)) is not None and d > 0:
        m += f'd={d}:'
    if (v := c.pop('vertical_align', None)) is not None and v > 0:
        m += f'v={v}:'
    if (h := c.pop('horizontal_align', None)) is not None and h > 0:
        m += f'h={h}:'
    if c:
        raise Exception('Unknown keys in multicell_command: ' + ', '.join(c))
    write(f'{OSC}{TEXT_SIZE_CODE};{m.rstrip(":")};{text}\a')


def screen_multi_cursor(rest: str) -> None:
    write(f'{CSI}>{rest.strip()} q')


def replay(raw: str) -> None:
    specials = frozenset(
        {
            'draw',
            'set_title',
            'set_icon',
            'set_dynamic_color',
            'set_color_table_color',
            'select_graphic_rendition',
            'process_cwd_notification',
            'clipboard_control',

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Remove unknown keys from the dict; check the function source for supported keys
2. Fix key typos (e.g. 'valign' vs 'vertical_align')
3. Update kitty so the command supports the newer keys

Example fix

# before
multicell_command({'text': 'hi', 'valign': 2})
# after
multicell_command({'text': 'hi', 'vertical_align': 2})

ALLOWED = {'text','cells','d','vertical_align','horizontal_align','h','v'}  # per source
cleaned = {k: v for k, v in cmd.items() if k in ALLOWED}

def is_valid_multicell_cmd(c: dict) -> bool:
    allowed = {'text','cells','d','vertical_align','horizontal_align'}
    return set(c) <= allowed

try:
    multicell_command(cmd)
except Exception as e:
    if 'Unknown keys in multicell_command' in str(e):
        cmd = {k: v for k, v in cmd.items() if k in ALLOWED}
        multicell_command(cmd)
    else:
        raise

When it happens

Trigger: Calling multicell_command with a dict containing keys other than the supported ones (text, cells/width-height, d, vertical_align, horizontal_align, etc.).

Common situations: Scripts generating text-size escape codes passing extra/misspelled keys, or using options added after this code version.

Related errors

• Unknown type_of_input: {type_of_input}
• 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
• The value {val} is not a valid choice for strip_trailing_spa

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