kovidgoyal/kitty · error · ConvertFailed

Failed to render image

Error message

Failed to render image

What it means

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.

Source

Thrown at kittens/tui/images.py:285

                f.canvas_x, f.canvas_y = map(int, pos.split('+', 1))
            except Exception:
                raise OutdatedImageMagick(f'Unexpected output filename: {x!r} produced by ImageMagick command: {last_imagemagick_cmd}')
            f.path = output_prefix + f'-{index}.{m.mode}'
            os.rename(os.path.join(tdir, x), f.path)
            check_resize(f)
    f = ans.frames[0]
    if f.width != ans.width or f.height != ans.height:
        with open(f.path, 'r+b') as ff:
            data = ff.read()
            ff.seek(0)
            ff.truncate()
            cd = create_canvas(data, f.width, f.canvas_x, f.canvas_y, ans.width, ans.height, 3 if ans.mode == 'rgb' else 4)
            ff.write(cd)
    if get_multiple_frames:
        if unseen:
            raise ConvertFailed(path, f'Failed to render {len(unseen)} out of {len(m)} frames of animation')
    elif not ans.frames[0].path:
        raise ConvertFailed(path, 'Failed to render image')

    return ans


def render_as_single_image(
    path: str,
    m: ImageData,
    available_width: int,
    available_height: int,
    scale_up: bool,
    tdir: str | None = None,
    remove_alpha: str = '',
    flip: bool = False,
    flop: bool = False,
) -> tuple[str, int, int]:
    import tempfile

    fd, output = tempfile.mkstemp(prefix='tty-graphics-protocol-', suffix=f'.{m.mode}', dir=tdir)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Verify the file exists and is a valid image (file / xdg-open it outside kitty)
2. Check the file is readable by the process and not zero bytes
3. Re-encode the image to PNG with another tool and retry
4. Inspect the converter backend logs/stderr for codec errors

Example fix

// before
img = render_as_single_image('photo.jpg', ...)
// after
from kittens.tui.images import render_image
try:
    img = render_as_single_image('photo.png', ...)
except ConvertFailed as e:
    # fall back to a placeholder
    img = render_as_single_image('placeholder.png', ...)

import os
from kittens.tui.images import ConvertFailed
can_render = os.path.isfile(path) and os.path.getsize(path) > 0

from kittens.tui.images import ConvertFailed
try:
    img = render_as_single_image(path, ...)
except ConvertFailed as e:
    log.warning('image failed: %s', e)
    img = None  # fallback placeholder

When it happens

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

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

Related errors

• 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 convert image at %s to bitmap with python error:
• This must be run as kitten ask
• This should be run as kitten broadcast

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