kovidgoyal/kitty · warning

The scrollback_pager {cmd[0]} was not found in PATH, falling

Error message

The scrollback_pager {cmd[0]} was not found in PATH, falling back to less

What it means

kitty logs this when the first word of the scrollback_pager option is a relative command name that cannot be resolved via PATH; it silently falls back to `less`. It is a warning, not a crash: the pager simply changes.

Source

Thrown at kitty/boss.py:2440

            s.connect(address)
            s.sendall(b'c')
            with suppress(OSError):
                s.shutdown(socket.SHUT_RDWR)
            s.close()

    def display_scrollback(self, window: Window, data: bytes | str, input_line_number: int = 0, title: str = '', report_cursor: bool = True) -> Window | None:

        def prepare_arg(x: str) -> str:
            x = x.replace('INPUT_LINE_NUMBER', str(input_line_number))
            x = x.replace('CURSOR_LINE', str(window.screen.cursor.y + 1) if report_cursor else '0')
            x = x.replace('CURSOR_COLUMN', str(window.screen.cursor.x + 1) if report_cursor else '0')
            return x

        cmd = list(map(prepare_arg, get_options().scrollback_pager))
        if not os.path.isabs(cmd[0]):
            resolved_exe = which(cmd[0])
            if not resolved_exe:
                log_error(f'The scrollback_pager {cmd[0]} was not found in PATH, falling back to less')
                resolved_exe = which('less') or 'less'
            cmd[0] = resolved_exe

        if os.path.basename(cmd[0]) == 'less':
            cmd.append('-+F')  # reset --quit-if-one-screen
        tab = self.active_tab
        if tab is not None:
            bdata = data.encode('utf-8') if isinstance(data, str) else data
            if is_macos and cmd[0] == '/usr/bin/less' and macos_version()[:2] < (12, 3):
                # the system less before macOS 12.3 barfs up OSC codes, so sanitize them ourselves
                sentinel = os.path.join(cache_dir(), 'less-is-new-enough')
                if not os.path.exists(sentinel):
                    if less_version(cmd[0]) >= 581:
                        open(sentinel, 'w').close()
                    else:
                        bdata = re.sub(rb'\x1b\].*?\x1b\\', b'', bdata)

            return tab.new_special_window(

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Verify the binary exists: `which <pager>` in the same environment kitty runs in
2. Use an absolute path in kitty.conf: `scrollback_pager /usr/bin/nvim`
3. Install the missing pager or fix PATH in the environment that spawns kitty
4. Accept the fallback to less if intentional

Example fix

# before
scrollback_pager moar
# after
scrollback_pager /home/user/.cargo/bin/moar

import shutil
pager = 'moar'
if shutil.which(pager) is None:
    pager = '/usr/bin/less'

When it happens

Trigger: Setting `scrollback_pager` to something like `nvim` or `moar` when that binary is not installed or not on kitty's PATH (e.g. kitty launched from a GUI launcher with a minimal PATH).

Common situations: User configures a favorite pager that is installed via a user-local tool (~/bin, homebrew, nix) but kitty inherits a stripped PATH when started from a desktop file; typos in the option value.

Related errors

• scroll_to_prompt needs one or two arguments, using defaults
• {vals[0]} is not a valid number of prompts to jump for scrol
• {vals[1]} is not a valid scroll offset for scroll_to_prompt
• This should be run as kitten broadcast
• ImageMagick is required to process images

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