kovidgoyal/kitty · error · UnknownLayout

The layout {} is unknown or disabled or the name is ambiguou

Error message

The layout {} is unknown or disabled or the name is ambiguous

What it means

Raised by the @ goto-layout remote-control command when the target tab's goto_layout() rejects the requested layout name — the layout is unknown, disabled at compile/config time, or the name is ambiguous (a prefix matching multiple layouts). Converted from the internal ValueError into an UnknownLayout remote-control error shown to the client.

Source

Thrown at kitty/rc/goto_layout.py:52

        spec='LAYOUT_NAME',
        count=1,
        json_field='layout',
        completion=RemoteCommand.CompletionSpec.from_string('type:keyword group:"Layout" kwds:' + ','.join(layout_names())),
    )

    def message_to_kitty(self, global_opts: RCOptions, opts: 'CLIOptions', args: ArgsType) -> PayloadType:
        if len(args) != 1:
            self.fatal('Exactly one layout must be specified')
        return {'layout': args[0], 'match': opts.match}

    def response_from_kitty(self, boss: Boss, window: Window | None, payload_get: PayloadGetType) -> ResponseType:
        tabs = self.tabs_for_match_payload(boss, window, payload_get)
        for tab in tabs:
            if tab:
                try:
                    tab.goto_layout(payload_get('layout'), raise_exception=True)
                except ValueError:
                    raise UnknownLayout('The layout {} is unknown or disabled or the name is ambiguous'.format(payload_get('layout')))
        return None


goto_layout = GotoLayout()

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check enabled layouts: run 'kitten @ goto-layout' candidates from the Layouts group in kitty.conf / docs, and verify enabled_layouts includes the target
2. Use the exact full layout name (e.g. 'fat', 'grid', 'vertical', 'stack') instead of an ambiguous prefix
3. For custom layouts, ensure the kitten providing the layout is loaded and the name is registered

Example fix

# before
kitten @ goto-layout t

# after
kitten @ goto-layout tall

from kitty.layout.base import layout_names  # or from config enabled_layouts
enabled = set(cfg_enabled_layouts)  # e.g. {'fat','grid','horizontal','stack','tall','vertical'}
name = 'tall'
matches = [l for l in enabled if l == name or l.startswith(name)]
if len(matches) != 1 or matches[0] != name:
    name = matches[0] if len(matches) == 1 else None
assert name, f'layout {name!r} unknown or ambiguous among {sorted(enabled)}'

def is_unambiguous_layout(name: str, enabled: set[str]) -> bool:
    m = [l for l in enabled if l == name or l.startswith(name)]
    return len(m) == 1 and m[0] == name

from kitty.rc.goto_layout import UnknownLayout
try:
    subprocess.run(['kitten', '@', 'goto-layout', name], check=True, capture_output=True, text=True)
except (subprocess.CalledProcessError,) as e:
    if 'unknown or disabled' in e.stderr:
        list_and_pick_layout()  # e.g. fall back to 'stack'
    else:
        raise

When it happens

Trigger: Calling 'kitten @ goto-layout xyz' with an invalid layout name; using a prefix like 'tall' only when multiple enabled layouts share that prefix; or naming a layout that exists but was disabled via enabled_layouts in kitty.conf.

Common situations: Layouts disabled in kitty.conf's enabled_layouts, custom layout names not registered by a loaded kitten, or version differences in the set of builtin layouts.

Related errors

• Unknown action: {ac}
• This should be run as kitten icat
• This should be run as `kitten notify ...`
• No kitten named {original_kitten_name}
• Remote control not enabled, this kitten should be run via a

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