kovidgoyal/kitty · error · SystemExit

Should be run as kitten hints

Error message

Should be run as kitten hints

What it means

A global uncaught NSException handler installed by kitty logged an exception that escaped Cocoa code (kitty/window: cocoa_window.m:1203). This is a last-resort log: an Objective-C exception (e.g. NSInvalidArgumentException, NSInternalInconsistencyException) was raised somewhere in AppKit/kitty's Cocoa glue and not caught anywhere.

Source

Thrown at kittens/hints/main.py:285

on selected matches. You can also specify absolute paths to load the script from
elsewhere. See {hints_url} for details.


--window-title
The title for the hints window, default title is based on the type of text being
hinted.
""".format(
    default_regex=DEFAULT_REGEX,
    line='{{line}}',
    path='{{path}}',
    hints_url=website_url('kittens/hints'),
).format
help_text = 'Select text from the screen using the keyboard. Defaults to searching for URLs.'
usage = ''


def main(args: list[str]) -> dict[str, Any] | None:
    raise SystemExit('Should be run as kitten hints')


def linenum_process_result(data: dict[str, Any]) -> tuple[str, int]:
    for match, g in zip(data['match'], data['groupdicts']):
        path, line = g['path'], g['line']
        if path and line:
            return path, int(line)
    return '', -1


def linenum_handle_result(args: list[str], data: dict[str, Any], target_window_id: int, boss: BossType, extra_cli_args: Sequence[str], *a: Any) -> None:
    path, line = linenum_process_result(data)
    if not path:
        return

    if extra_cli_args:
        cmd = [x.format(path=path, line=line) for x in extra_cli_args]
    else:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Update kitty to the latest version - Cocoa crashes are frequently fixed for new macOS releases.
2. Check the accompanying 'Stack trace:' log line to identify the failing AppKit call and report both to kitty's GitHub.
3. Try disabling recently toggled features (tab bar, macOS notifications, custom cursors) to isolate the trigger.
4. Note the exact reproduction steps (resize/fullscreen/close sequence) for the bug report.

# as a user: capture the log to triage
kitty --debug-config 2>~/kitty.err; grep -A20 'Unhandled exception in Cocoa' ~/kitty.err

When it happens

Trigger: Any uncaught NSException on the Cocoa side of kitty on macOS - commonly triggered by invalid API arguments, KVO/observer violations, or AppKit state assumptions broken during window operations (resize, fullscreen, tab teardown).

Common situations: macOS version upgrades changing AppKit behavior, buggy GPU/window-server interactions, or kitty bugs in window management code. Usually paired with a crash right after.

Related errors

• This must be run as kitten desktop-ui
• This should be run as kitten hyperlinked_grep
• Must be run as kitten diff
• This should be run as kitten dnd
• The value {val} is not a valid choice for window_title_bar

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