kovidgoyal/kitty · error

Failed to mmap bitmap data for image at %s with error: %s

Error message

Failed to mmap bitmap data for image at %s with error: %s

What it means

After decoding an image, kitty could not mmap the shared-memory bitmap data produced by the render cache; strerror(errno) explains why (ENOMEM, EINVAL, etc.). The bitmap load fails and the background/logo is not applied.

Source

Thrown at kitty/graphics.c:603

        log_error("Failed to convert image at %s to bitmap with python error:", path); \
        PyErr_Print();                                                                 \
        return false;                                                                  \
    }
    if (!module) fail_on_python_error;
    RAII_PyObject(irc, PyObject_GetAttrString(module, "default_image_render_cache"));
    if (!irc) fail_on_python_error;
    RAII_PyObject(ret, PyObject_CallFunction(irc, "s", path));
    if (!ret) fail_on_python_error;
    size_t w = PyLong_AsSize_t(PyTuple_GET_ITEM(ret, 0));
    size_t h = PyLong_AsSize_t(PyTuple_GET_ITEM(ret, 1));
    int fd = PyLong_AsLong(PyTuple_GET_ITEM(ret, 2));
#undef fail_on_python_error
    size_t data_size = 8 + w * h * 4;
    *data = mmap(NULL, data_size, PROT_READ, MAP_PRIVATE, fd, 0);
    int saved_errno = errno;
    safe_close(fd, __FILE__, __LINE__);
    if (*data == MAP_FAILED) {
        log_error("Failed to mmap bitmap data for image at %s with error: %s", path, strerror(saved_errno));
        return false;
    }
    *sz = data_size;
    *width = w;
    *height = h;
    return true;
}

static Image *
find_or_create_image(GraphicsManager *self, uint32_t id, bool *existing) {
    if (id) {
        Image *img = img_by_client_id(self, id);
        if (img) {
            *existing = true;
            return img;
        }
    }
    *existing = false;

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use a smaller (lower resolution) image
2. Read the errno in the message: ENOMEM means memory pressure
3. Raise memory limits / overcommit settings or cgroup limits if in a container
4. Avoid multiple windows each using huge backgrounds

Example fix

# before
background_image ~/8k_wallpaper.png
# after
background_image ~/1080p_wallpaper.png

# ensure the image is not gigantic before using it as a background
python3 -c "from PIL import Image; w,h=Image.open('bg.png').size; assert w*h*4 < 500_000_000"

When it happens

Trigger: mmap(PROT_READ, MAP_PRIVATE) of the bitmap fd fails - typically when data_size = 8 + w*h*4 exceeds available address space or memory limits.

Common situations: Very large background images (huge width*height), low system memory, strict RLIMIT_AS/overcommit settings, or container cgroup memory limits.

Related errors

• This must be run as kitten ask
• This kitten must be used only from a kitty.conf mapping
• 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/5638471b0ab2a38a. Report an issue: GitHub.