kovidgoyal/kitty · error · ValueError

The window layout {p} is unknown

Error message

The window layout {p} is unknown

What it means

parse_layout_names raises this when a window layout name in enabled_layouts (or a layout-related remote-control message) is not in all_layouts. The '*'/'all' wildcard expands to all registered layouts; anything else must be a known layout name, optionally with ':params' after partitioning on ':'.

Source

Thrown at kitty/options/utils.py:738

def window_size(val: str) -> tuple[int, str]:
    val = val.lower()
    unit = 'cells' if val.endswith('c') else 'px'
    return positive_int(val.rstrip('c')), unit


def parse_layout_names(parts: Iterable[str]) -> list[str]:
    from kitty.layout.interface import all_layouts

    ans = []
    for p in parts:
        p = p.lower()
        if p in ('*', 'all'):
            ans.extend(sorted(all_layouts))
            continue
        name = p.partition(':')[0]
        if name not in all_layouts:
            raise ValueError(f'The window layout {p} is unknown')
        ans.append(p)
    return uniq(ans)


def to_layout_names(raw: str) -> list[str]:
    return parse_layout_names(x.strip() for x in raw.split(','))


def window_border_width(x: str | int | float) -> tuple[float, str]:
    unit = 'pt'
    if isinstance(x, str):
        trailer = x[-2:]
        if trailer in ('px', 'pt'):
            unit = trailer
            val = float(x[:-2])
        else:
            val = float(x)
    else:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the error-time list: layouts, fat, grid, horizontal, splits, stack, tall, vertical and fix the name
2. Upgrade kitty if the layout exists only in newer versions
3. Use '*' to enable all layouts

Example fix

# before
enabled_layouts grid,vertcial
# after
enabled_layouts grid,vertical

def valid_layouts(raw: str, known: set[str]) -> bool:
    return all(p.partition(':')[0] in known or p in ('*','all') for p in (q.strip().lower() for q in raw.split(',')))

When it happens

Trigger: enabled_layouts grid,vertical,stacking_typo or layout messages with unknown names like 'splits' on kitty versions before splits existed.

Common situations: Typos, or using layouts (splits, stacks, fat/bias variants) that don't exist in the installed kitty version.

Related errors

• Invalid characters in visual_window_select_characters: {x} O
• Invalid characters in visual_window_select_characters: {x} C
• Unknown or disabled layout: {layout_name}
• This should be run as kitten broadcast
• No option named: {k}

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