{"record":{"id":"7b2f714cd1126d44","repo":"kovidgoyal/kitty","slug":"failed-to-render-image","errorCode":null,"errorMessage":"Failed to render image","messagePattern":"Failed to render image","errorType":"exception","errorClass":"ConvertFailed","httpStatus":null,"severity":"error","filePath":"kittens/tui/images.py","lineNumber":285,"sourceCode":"                f.canvas_x, f.canvas_y = map(int, pos.split('+', 1))\n            except Exception:\n                raise OutdatedImageMagick(f'Unexpected output filename: {x!r} produced by ImageMagick command: {last_imagemagick_cmd}')\n            f.path = output_prefix + f'-{index}.{m.mode}'\n            os.rename(os.path.join(tdir, x), f.path)\n            check_resize(f)\n    f = ans.frames[0]\n    if f.width != ans.width or f.height != ans.height:\n        with open(f.path, 'r+b') as ff:\n            data = ff.read()\n            ff.seek(0)\n            ff.truncate()\n            cd = create_canvas(data, f.width, f.canvas_x, f.canvas_y, ans.width, ans.height, 3 if ans.mode == 'rgb' else 4)\n            ff.write(cd)\n    if get_multiple_frames:\n        if unseen:\n            raise ConvertFailed(path, f'Failed to render {len(unseen)} out of {len(m)} frames of animation')\n    elif not ans.frames[0].path:\n        raise ConvertFailed(path, 'Failed to render image')\n\n    return ans\n\n\ndef render_as_single_image(\n    path: str,\n    m: ImageData,\n    available_width: int,\n    available_height: int,\n    scale_up: bool,\n    tdir: str | None = None,\n    remove_alpha: str = '',\n    flip: bool = False,\n    flop: bool = False,\n) -> tuple[str, int, int]:\n    import tempfile\n\n    fd, output = tempfile.mkstemp(prefix='tty-graphics-protocol-', suffix=f'.{m.mode}', dir=tdir)","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/tui/images.py#L267-L303","documentation":"Raised as ConvertFailed by render_image in kittens/tui/images.py when the image conversion pipeline produced no output path for the first frame, meaning the source image could not be rendered at all (as opposed to partial frame failures in animations). It signals the underlying image codec/decoder (via the kitty image pipeline) failed to produce a usable frame.","triggerScenarios":"Calling render_image(path) (or render_as_single_image) on a corrupt, zero-byte, unsupported-format, or unreadable image file; the converter returns frames[0].path falsy after conversion.","commonSituations":"Feeding a downloaded/truncated image, a file with a wrong extension, an unsupported codec, or a path the process cannot read into the TUI image kitten; also image magick/codec backend failures.","solutions":["Verify the file exists and is a valid image (file / xdg-open it outside kitty)","Check the file is readable by the process and not zero bytes","Re-encode the image to PNG with another tool and retry","Inspect the converter backend logs/stderr for codec errors"],"exampleFix":"// before\nimg = render_as_single_image('photo.jpg', ...)\n// after\nfrom kittens.tui.images import render_image\ntry:\n    img = render_as_single_image('photo.png', ...)\nexcept ConvertFailed as e:\n    # fall back to a placeholder\n    img = render_as_single_image('placeholder.png', ...)","handlingStrategy":"try-catch","validationCode":"import os\nfrom kittens.tui.images import ConvertFailed\ncan_render = os.path.isfile(path) and os.path.getsize(path) > 0","typeGuard":null,"tryCatchPattern":"from kittens.tui.images import ConvertFailed\ntry:\n    img = render_as_single_image(path, ...)\nexcept ConvertFailed as e:\n    log.warning('image failed: %s', e)\n    img = None  # fallback placeholder","preventionTips":["Validate image files exist and are non-empty before rendering","Pre-convert untrusted images to PNG","Keep a placeholder image path as fallback"],"tags":["image","kitty","conversion","tui"],"backgroundTag":"image-decode-failed","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}