kovidgoyal/kitty · warning · SystemExit

This must be run as kitten ask

Error message

This must be run as kitten ask

What it means

kitty failed to munmap a memory-mapped background image bitmap in free_bgimage_bitmap (kitty/state.c). The background image was loaded via mmap (e.g. from a preprocessed image cache file) and the OS refused to unmap it at shutdown or when reloading the background image. It usually indicates the mapping address/size were corrupted or the mapping was already released elsewhere.

Source

Thrown at kittens/ask/main.py:73

--unhide-key
default=u
The key to be pressed to unhide hidden text


--hidden-text-placeholder
The text in the message to be replaced by hidden text. The hidden text is read via STDIN.
"""


class Response(TypedDict):
    items: list[str]
    response: str | None


def main(args: list[str]) -> Response:
    raise SystemExit('This must be run as kitten ask')


@result_handler()
def handle_result(args: list[str], data: Response, target_window_id: int, boss: BossType) -> None:
    if data['response'] is not None:
        func, *args = data['items']
        getattr(boss, func)(data['response'], *args)


if __name__ == '__main__':
    main(sys.argv)
elif __name__ == '__doc__':
    cd = sys.cli_docs  # type: ignore
    cd['usage'] = ''
    cd['options'] = option_text
    cd['help_text'] = 'Ask the user for input'
    cd['short_desc'] = 'Ask the user for input'

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Clear kitty's image cache: rm -rf ~/.cache/kitty and restart kitty.
2. Verify the background image file is a valid, non-truncated PNG/JPEG (re-save it).
3. Reproduce with a different image file to rule out file corruption.
4. If reproducible, report to kitty GitHub with the exact kitty version and kernel version - munmap failing on a valid mapping suggests a real bug.

Example fix

# before
background_image ~/corrupted-wallpaper.png
# after
rm -rf ~/.cache/kitty
background_image ~/re-saved-wallpaper.png

When it happens

Trigger: Setting background_image in kitty.conf, then changing the background image at runtime (kitten @set-background-image), sending it to the GPU repeatedly, or quitting kitty. Only fires when bgimage->mmap_size != 0 and munmap() returns non-zero.

Common situations: Corrupted image cache files in kitty's cache dir (~/.cache/kitty), a background image file that changed size while mapped, or memory corruption from a GPU driver issue. Rarely seen on healthy systems.

Related errors

• This kitten must be used only from a kitty.conf mapping
• Failed to mmap bitmap data for image at %s with error: %s
• Failed to decode PNG image at: %s with error: %s
• Failed to convert image at %s to bitmap with python error:
• This should be run as kitten broadcast

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