kovidgoyal/kitty · warning

Unknown or disabled layout: {layout_name}

Error message

Unknown or disabled layout: {layout_name}

What it means

goto_layout was asked (non-exception mode) to switch to a layout name that matches zero enabled layouts — either unknown or currently disabled via enabled_layouts. kitty logs and keeps the current layout.

Source

Thrown at kitty/tabs.py:645

                    matched_layout = candidate
                    break
                if candidate.startswith(layout_name):
                    prefix_matches.append(candidate)
                matches.append(x)

        if not matched_layout:
            if len(prefix_matches) == 1:
                matched_layout = prefix_matches[0]
            elif len(matches) == 1:
                matched_layout = matches[0]
        if matched_layout:
            self._set_current_layout(matched_layout)
            self.relayout()
        else:
            if len(matches) == 0:
                if raise_exception:
                    raise ValueError(layout_name)
                log_error(f'Unknown or disabled layout: {layout_name}')
            elif len(matches) != 1:
                if raise_exception:
                    raise ValueError(layout_name)
                log_error(f'Multiple layouts match: {layout_name}')

    @ac(
        'lay',
        """
        Toggle the named layout

        Switches to the named layout if another layout is current, otherwise
        switches to the last used layout. Useful to "zoom" a window temporarily
        by switching to the stack layout. See also :opt:`scrollback_fill_enlarged_window`
        if you would like content from the scrollback buffer to scroll down into the
        zoomed window. For example::

            map f1 toggle_layout stack
        """,

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the exact name against: kitten @get-enabled-layouts / kitty --debug-config
2. Add the layout to enabled_layouts (e.g. enabled_layouts grid,vertical,fat)
3. Fix typos: valid names include tall, stack, grid, horizontal, vertical, fat, splits, etc.

Example fix

# before
map f1 goto_layout talll
enabled_layouts stack

# after
map f1 goto_layout tall
enabled_layouts tall,stack

enabled = {'tall', 'stack', 'grid', 'splits'}  # from kitten @get-enabled-layouts
assert name in enabled, f'layout {name} not enabled/known'

def is_enabled_layout(name: str, enabled: set[str]) -> bool:
    return name in enabled

When it happens

Trigger: goto_layout(name, raise_exception=False) finds no match among enabled layouts — e.g. remote-control 'kitten @kitten goto-layout' or 'layout' map action with a typo'd/disabled name.

Common situations: Typo in layout name in a map binding, or the layout exists but was removed from enabled_layouts in kitty.conf.

Related errors

• The window layout {p} is unknown
• This should be run as kitten broadcast
• No option named: {k}
• No custom kitten named {kitten} found
• Not a number: {x} with error: {e}

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