kovidgoyal/kitty · warning · SystemExit

This kitten must be used only from a kitty.conf mapping

Error message

This kitten must be used only from a kitty.conf mapping

What it means

kitty failed to munmap a window logo bitmap in free_window_logo_bitmap (kitty/window_logo.c:41) - the per-window logo analogue of the background-image error. The logo was mmap'd from kitty's image cache and the unmap syscall failed during logo replacement, window close, or shutdown.

Source

Thrown at kittens/command_palette/main.py:308

    relocate_mode_entry_bindings(modes)
    add_unmapped_actions(modes)
    add_alias_sections(opts, modes)

    mode_order = list(modes.keys())
    category_order: dict[str, list[str]] = {}
    for mode_name, cats in modes.items():
        category_order[mode_name] = list(cats.keys())

    return {
        'modes': modes,
        'mouse': collect_mouse_bindings(opts),
        'mode_order': mode_order,
        'category_order': category_order,
    }


def main(args: list[str]) -> None:
    raise SystemExit('This kitten must be used only from a kitty.conf mapping')


def callback(target_window_id: int, action: str, timer_id: int | None) -> None:
    boss = get_boss()
    w = boss.window_id_map.get(target_window_id)
    boss.combine(action, w)


@result_handler(has_ready_notification=True)
def handle_result(args: list[str], data: dict[str, Any], target_window_id: int, boss: BossType) -> None:
    if data and (action := data.get('action')):
        # run action after event loop tick so command palette overlay is closed
        add_timer(partial(callback, target_window_id, action), 0, False)


help_text = 'Browse and trigger keyboard shortcuts and actions'
usage = ''
OPTIONS = r"""

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Clear kitty's cache: rm -rf ~/.cache/kitty and restart.
2. Re-save the logo image to guarantee a valid file.
3. Test with a different logo to isolate file corruption.
4. Reproduce and report upstream with kitty/kernel versions if persistent.

Example fix

# before
window_logo_path ~/bad-logo.png
# after
rm -rf ~/.cache/kitty
window_logo_path /abs/path/good-logo.png

When it happens

Trigger: Configuring window_logo_path and then changing the logo at runtime (kitten @set-window-logo), closing windows, or quitting. Fires only when wl->mmap_size != 0 and munmap() returns non-zero.

Common situations: Corrupt kitty image cache, logo file modified/truncated while mapped, or memory corruption. Rare in practice.

Related errors

• This must be run as kitten ask
• Failed to mmap bitmap data for image at %s with error: %s
• This should be run as kitten broadcast
• This must be run as kitten choose-files
• Pipe to kitten was broken while sending data to it

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