kovidgoyal/kitty · error · ValueError

Failed to convert {src_path} to RGBA data, no output written

Error message

Failed to convert {src_path} to RGBA data, no output written. stderr: {cp.stderr.decode("utf-8", "replace")}

What it means

The conversion subprocess exited 0 but wrote fewer than 8 bytes of RGBA output, so the data is unusable; stderr is included if present.

Source

Thrown at kitty/render_cache.py:78

        entries.sort(key=sort_key, reverse=True)
        for e in entries[self.max_entries :]:
            with suppress(FileNotFoundError):
                os.remove(e.path)

    def touch(self, path: str) -> None:
        os.utime(path, follow_symlinks=False)

    def render_image(self, src_path: str, output_path: str) -> None:
        import stat
        import subprocess

        try:
            with open(src_path, 'rb') as src, open(output_path, 'wb', opener=partial(os.open, mode=stat.S_IREAD | stat.S_IWRITE)) as output:
                cp = subprocess.run([kitten_exe(), '__convert_image__', 'RGBA'], stdin=src, stdout=output, stderr=subprocess.PIPE)
                if cp.returncode != 0:
                    raise ValueError(f'Failed to convert {src_path} to RGBA data with error: {cp.stderr.decode("utf-8", "replace")}')
                if output.seek(0, os.SEEK_END) < 8:
                    raise ValueError(f'Failed to convert {src_path} to RGBA data, no output written. stderr: {cp.stderr.decode("utf-8", "replace")}')
        except Exception:
            with suppress(Exception):
                os.unlink(output_path)
            raise

    def read_metadata(self, output_path: str) -> tuple[int, int, int]:
        with open(output_path, 'rb') as f:
            header = f.read(8)
            import struct

            width, height = struct.unpack('<II', header)
            f.seek(0)
            return width, height, os.dup(f.fileno())

    def render(self, src_path: str) -> str:
        import struct
        from hashlib import sha256

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the source file is non-empty and has valid dimensions
2. Re-save the image with an image editor or 'magick' to normalize it
3. Report a bug if a well-formed image triggers it on your kitty version

import os
assert os.path.getsize(src_path) > 0

except ValueError: skip degenerate image and continue batch

When it happens

Trigger: A kitten __convert_image__ invocation that succeeds silently but produces (almost) no output — empty stdin, degenerate 0-pixel image, or plugin/codec issue.

Common situations: Passing an empty or pathological image file (0x0 dimensions) into the render cache.

Related errors

• Failed to render image
• Failed to convert {src_path} to RGBA data with error: {cp.st
• 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/76940636bacb619e. Report an issue: GitHub.