{"record":{"id":"55d53a5a93f5f3d0","repo":"kovidgoyal/kitty","slug":"failed-to-decode-png-image-at-s-with-error-s","errorCode":null,"errorMessage":"Failed to decode PNG image at: %s with error: %s","messagePattern":"Failed to decode PNG image at: (.+?) with error: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kitty/graphics.c","lineNumber":514,"sourceCode":"}\n\nstatic void\nprint_png_read_error(png_read_data *d, const char *code, const char *msg) {\n    if (d->error.used >= d->error.capacity) {\n        size_t cap = MAX(2 * d->error.capacity, 1024 + d->error.used);\n        d->error.buf = realloc(d->error.buf, cap);\n        if (!d->error.buf) return;\n        d->error.capacity = cap;\n    }\n    d->error.used += snprintf(d->error.buf + d->error.used, d->error.capacity - d->error.used, \"%s: %s \", code, msg);\n}\n\nbool\npng_from_data(void *png_data, size_t png_data_sz, const char *path_for_error_messages, uint8_t **data, unsigned int *width, unsigned int *height, size_t *sz) {\n    png_read_data d = {.err_handler = print_png_read_error};\n    inflate_png_inner(&d, png_data, png_data_sz, MAX_IMAGE_DIMENSION);\n    if (!d.ok) {\n        log_error(\"Failed to decode PNG image at: %s with error: %s\", path_for_error_messages, d.error.used > 0 ? d.error.buf : \"\");\n        free(d.decompressed);\n        free(d.row_pointers);\n        free(d.error.buf);\n        return false;\n    }\n    *data = d.decompressed;\n    free(d.row_pointers);\n    free(d.error.buf);\n    *sz = d.sz;\n    *height = d.height;\n    *width = d.width;\n    return true;\n}\n\nbool\npng_from_file_pointer(FILE *fp, const char *path_for_error_messages, uint8_t **data, unsigned int *width, unsigned int *height, size_t *sz) {\n    size_t capacity = 16 * 1024, pos = 0;\n    unsigned char *buf = malloc(capacity);","sourceCodeStart":496,"sourceCodeEnd":532,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/graphics.c#L496-L532","documentation":"png_from_data failed to decode a PNG: the zlib inflate or libpng read pipeline reported an error (captured in d.error.buf). It is logged with the path/data source given by the caller (window icon, background image, or window logo), and the function returns false so the caller falls back to defaults.","triggerScenarios":"Passing corrupt or non-PNG bytes to kitty's graphics API: set_os_window_icon with bad data, background_image config pointing to a truncated/corrupt PNG, or a window logo image that exceeds MAX_IMAGE_DIMENSION.","commonSituations":"background_image in kitty.conf pointing to a partially-downloaded or CMYK/16-bit-unusual PNG; icons damaged by transfer; images larger than kitty's MAX_IMAGE_DIMENSION limit; providing JPEG/WebP bytes where PNG is required.","solutions":["Validate the image is a real PNG: file icon.png (or pngcheck icon.png)","Re-export/re-download the image; open it in an image editor and re-save as PNG","Resize the image below kitty's MAX_IMAGE_DIMENSION","If passing raw data programmatically, confirm you are passing PNG-encoded bytes, not decoded RGBA"],"exampleFix":"# before (kitty.conf)\nbackground_image ~/pics/photo.cwebp\n# after\nbackground_image ~/pics/photo.png","handlingStrategy":"validation","validationCode":"import struct\n\ndef is_png(data: bytes) -> bool:\n    return len(data) >= 8 and data[:8] == b'\\x89PNG\\r\\n\\x1a\\n'\n\n# and: pngcheck file.png before configuring it","typeGuard":"def is_valid_png(data: bytes) -> bool:\n    if not is_png(data):\n        return False\n    w, h = struct.unpack('>II', data[16:24])\n    return 0 < w <= MAX_IMAGE_DIMENSION and 0 < h <= MAX_IMAGE_DIMENSION","tryCatchPattern":"if not png_from_data(buf, sz, path, &out, &w, &h, &osz) { /* keep default icon/background instead of failing */ }","preventionTips":["Run pngcheck on images before pointing kitty.conf at them","Keep background images modest in dimensions (screen resolution)","Re-save unusual PNGs (16-bit/CMYK) as standard 8-bit RGBA"],"tags":["kitty","png","image-decoding","background-image","icon"],"backgroundTag":"png-decode-failed","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}