kovidgoyal/kitty · error

Failed to convert image at %s to bitmap with python error:

Error message

Failed to convert image at %s to bitmap with python error:

What it means

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().

Source

Thrown at kitty/graphics.c:585

        log_error("The PNG image: %s could not be opened with error: %s", path, strerror(errno));
        return false;
    }
    bool ret = png_from_file_pointer(fp, path, data, width, height, sz);
    fclose(fp);
    fp = NULL;
    return ret;
}

bool
image_path_to_bitmap(const char *path, uint8_t **data, unsigned int *width, unsigned int *height, size_t *sz) {
    *data = NULL;
    *sz = 0;
    *width = 0;
    *height = 0;
    RAII_PyObject(module, PyImport_ImportModule("kitty.render_cache"));
#define fail_on_python_error                                                           \
    {                                                                                  \
        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));

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the Python traceback printed right after this message - it names the real cause
2. Verify the image decodes: python3 -c "from kitty.rgb import to_webdesign; to_webdesign('bg.png')"
3. Convert the image to PNG or JPEG and confirm it is not corrupt
4. Reinstall/upgrade kitty if the traceback shows an ImportError for kitty.render_cache

Example fix

# before
background_image ~/bg.heic
# after
background_image ~/bg.png

# verify kitty can decode the image before configuring it
python3 -c "from kitty.rgb import to_webdesign; to_webdesign('bg.png'); print('ok')"

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• This must be run as kitten ask
• Failed to render image
• Failed to convert {src_path} to RGBA data with error: {cp.st
• Failed to convert {src_path} to RGBA data, no output written
• Failed to decode PNG image at: %s with error: %s

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