{"record":{"id":"5638471b0ab2a38a","repo":"kovidgoyal/kitty","slug":"failed-to-mmap-bitmap-data-for-image-at-s-with-er","errorCode":null,"errorMessage":"Failed to mmap bitmap data for image at %s with error: %s","messagePattern":"Failed to mmap bitmap data for image at (.+?) with error: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kitty/graphics.c","lineNumber":603,"sourceCode":"        log_error(\"Failed to convert image at %s to bitmap with python error:\", path); \\\n        PyErr_Print();                                                                 \\\n        return false;                                                                  \\\n    }\n    if (!module) fail_on_python_error;\n    RAII_PyObject(irc, PyObject_GetAttrString(module, \"default_image_render_cache\"));\n    if (!irc) fail_on_python_error;\n    RAII_PyObject(ret, PyObject_CallFunction(irc, \"s\", path));\n    if (!ret) fail_on_python_error;\n    size_t w = PyLong_AsSize_t(PyTuple_GET_ITEM(ret, 0));\n    size_t h = PyLong_AsSize_t(PyTuple_GET_ITEM(ret, 1));\n    int fd = PyLong_AsLong(PyTuple_GET_ITEM(ret, 2));\n#undef fail_on_python_error\n    size_t data_size = 8 + w * h * 4;\n    *data = mmap(NULL, data_size, PROT_READ, MAP_PRIVATE, fd, 0);\n    int saved_errno = errno;\n    safe_close(fd, __FILE__, __LINE__);\n    if (*data == MAP_FAILED) {\n        log_error(\"Failed to mmap bitmap data for image at %s with error: %s\", path, strerror(saved_errno));\n        return false;\n    }\n    *sz = data_size;\n    *width = w;\n    *height = h;\n    return true;\n}\n\nstatic Image *\nfind_or_create_image(GraphicsManager *self, uint32_t id, bool *existing) {\n    if (id) {\n        Image *img = img_by_client_id(self, id);\n        if (img) {\n            *existing = true;\n            return img;\n        }\n    }\n    *existing = false;","sourceCodeStart":585,"sourceCodeEnd":621,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/graphics.c#L585-L621","documentation":"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.","triggerScenarios":"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.","commonSituations":"Very large background images (huge width*height), low system memory, strict RLIMIT_AS/overcommit settings, or container cgroup memory limits.","solutions":["Use a smaller (lower resolution) image","Read the errno in the message: ENOMEM means memory pressure","Raise memory limits / overcommit settings or cgroup limits if in a container","Avoid multiple windows each using huge backgrounds"],"exampleFix":"# before\nbackground_image ~/8k_wallpaper.png\n# after\nbackground_image ~/1080p_wallpaper.png","handlingStrategy":"validation","validationCode":"# ensure the image is not gigantic before using it as a background\npython3 -c \"from PIL import Image; w,h=Image.open('bg.png').size; assert w*h*4 < 500_000_000\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Cap background image resolution","Watch container/cgroup memory limits"],"tags":["kitty","mmap","memory","background-image"],"backgroundTag":"mmap-failed","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}