{"record":{"id":"53fcb2b76d7e6513","repo":"kovidgoyal/kitty","slug":"failed-to-convert-image-at-s-to-bitmap-with-pytho","errorCode":null,"errorMessage":"Failed to convert image at %s to bitmap with python error:","messagePattern":"Failed to convert image at (.+?) to bitmap with python error:","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kitty/graphics.c","lineNumber":585,"sourceCode":"        log_error(\"The PNG image: %s could not be opened with error: %s\", path, strerror(errno));\n        return false;\n    }\n    bool ret = png_from_file_pointer(fp, path, data, width, height, sz);\n    fclose(fp);\n    fp = NULL;\n    return ret;\n}\n\nbool\nimage_path_to_bitmap(const char *path, uint8_t **data, unsigned int *width, unsigned int *height, size_t *sz) {\n    *data = NULL;\n    *sz = 0;\n    *width = 0;\n    *height = 0;\n    RAII_PyObject(module, PyImport_ImportModule(\"kitty.render_cache\"));\n#define fail_on_python_error                                                           \\\n    {                                                                                  \\\n        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));","sourceCodeStart":567,"sourceCodeEnd":603,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/graphics.c#L567-L603","documentation":"kitty failed to convert an image file (background image or window logo) to a bitmap because the embedded Python call into kitty.render_cache.default_image_render_cache failed or raised a Python exception. The message is followed by the Python traceback printed via PyErr_Print().","triggerScenarios":"Setting a background_image or logo via pyset_background_image / global_background_image when the kitty.render_cache module cannot be imported, default_image_render_cache is missing, or image decoding (pillow/ImageMagick backend) raises.","commonSituations":"Corrupt or unsupported image file, broken kitty installation where kitty Python modules are missing, pillow not importable inside the kitty environment, or an exotic image format.","solutions":["Check the Python traceback printed right after this message - it names the real cause","Verify the image decodes: python3 -c \"from kitty.rgb import to_webdesign; to_webdesign('bg.png')\"","Convert the image to PNG or JPEG and confirm it is not corrupt","Reinstall/upgrade kitty if the traceback shows an ImportError for kitty.render_cache"],"exampleFix":"# before\nbackground_image ~/bg.heic\n# after\nbackground_image ~/bg.png","handlingStrategy":"validation","validationCode":"# verify kitty can decode the image before configuring it\npython3 -c \"from kitty.rgb import to_webdesign; to_webdesign('bg.png'); print('ok')\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use well-supported formats (PNG/JPEG)","Test images with kitty's own Python code before configuring","Keep kitty's Python files intact - avoid partially copying the binary"],"tags":["kitty","image","python-embedding","background-image"],"backgroundTag":"image-decode-failed","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}