kovidgoyal/kitty · error · ValueError

{val} is not a valid layout

Error message

{val} is not a valid layout

What it means

Raised by Session.set_layout when the layout name (the part before the first ':') in a session file's layout directive is not one of kitty's known layouts. The full layout string may include a state suffix after ':', but the prefix must match an entry in all_layouts.

Source

Thrown at kitty/session.py:114

    @property
    def has_non_background_processes(self) -> bool:
        for t in self.tabs:
            if t.has_non_background_processes:
                return True
        return False

    def add_tab(self, opts: Options, name: str = '') -> None:
        if self.tabs and not self.tabs[-1].windows:
            del self.tabs[-1]
        self.tabs.append(Tab(opts, name))

    def set_next_title(self, title: str) -> None:
        self.tabs[-1].next_title = title.strip()

    def set_layout(self, val: str) -> None:
        if val.partition(':')[0] not in all_layouts:
            raise ValueError(f'{val} is not a valid layout')
        self.tabs[-1].layout = val

    def set_layout_state(self, val: str) -> None:
        self.tabs[-1].layout_state = json.loads(val)

    def add_window(self, cmd: None | str | list[str], expand: Callable[[str], str] = lambda x: x) -> None:
        from .launch import parse_launch_args

        needs_expandvars = False
        if isinstance(cmd, str):
            needs_expandvars = True
            cmd = list(shlex_split(cmd)) if cmd else []
        serialize_data: dict[str, Any] = {'id': 0, 'cmd_at_shell_startup': ()}
        if cmd and cmd[0].startswith(unserialize_launch_flag):
            serialize_data = json.loads(cmd[0][len(unserialize_launch_flag) :])
            del cmd[0]
        spec = parse_launch_args(cmd)
        if needs_expandvars:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the exact layout name against kitty's all_layouts (run `kitty --debug-layouts` or check docs): valid names include stack, tall, fat, grid, horizontal, vertical, splits
2. Fix the typo in the session file's layout line
3. If using a custom layout, ensure it's registered/enabled before loading the session
4. Note the part before ':' is what's validated: 'grid:...' must still start with a valid name

Example fix

# before (session file)
layout gird
# after
layout grid

from kitty.layout.base import all_layouts

def valid_layout(v: str) -> bool:
    return v.partition(':')[0] in all_layouts

try:
    create_sessions(session_data)
except ValueError as e:
    if 'is not a valid layout' in str(e):
        # report and fall back to default layout
        ...

When it happens

Trigger: A session file line like 'layout grid' when the layout name is misspelled or not compiled in (e.g. 'splits' without the splits dependency, 'fat3' custom layout not registered), or a custom layout not enabled in enabled_layouts.

Common situations: Session files written for a newer/older kitty version or another machine where a layout (e.g. 'splits') isn't available; typos like 'gird' or 'tall:' with wrong casing.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Unknown command in session file: {cmd}
• Unknown action: {action}
• layout_action bias must contain at least one number between
• layout_action must have at least one argument
• The layout {} is unknown or disabled or the name is ambiguou

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