kovidgoyal/kitty · warning

Unknown signal: {rest} ignoring

Error message

Unknown signal: {rest} ignoring

What it means

kitty's signal_child action parser could not resolve a token in the map/action definition to a Python signal module attribute (signal.<NAME>). Unknown tokens are skipped and only the recognized signals are kept, so the mapping still works but silently does less than intended.

Source

Thrown at kitty/options/utils.py:228

def simple_parse(func: str, rest: str) -> FuncArgsType:
    return func, (rest,)


@func_with_args('set_font_size')
def float_parse(func: str, rest: str) -> FuncArgsType:
    return func, (float(rest),)


@func_with_args('signal_child')
def signal_child_parse(func: str, rest: str) -> FuncArgsType:
    import signal

    signals = []
    for q in rest.split():
        try:
            signum = getattr(signal, q.upper())
        except AttributeError:
            log_error(f'Unknown signal: {rest} ignoring')
        else:
            signals.append(signum)
    return func, tuple(signals)


@func_with_args('change_font_size')
def parse_change_font_size(func: str, rest: str) -> tuple[str, tuple[bool, str | None, float]]:
    vals = rest.strip().split(maxsplit=1)
    if len(vals) != 2:
        log_error(f'Invalid change_font_size specification: {rest}, treating it as default')
        return func, (True, None, 0)
    c_all = vals[0].lower() == 'all'
    sign: str | None = None
    amt = vals[1]
    if amt[0] in '+-*/':
        sign = amt[0]
        amt = amt[1:]
    return func, (c_all, sign, float(amt.strip()))

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Fix the signal name spelling in kitty.conf (must match a constant in Python's signal module, e.g. SIGUSR1, SIGTERM)
2. Check available names with `python3 -c "import signal; print([n for n in dir(signal) if n.startswith('SIG')])"` on the target platform
3. Verify platform support before using less common signals like SIGWINCH or SIGPOLL

Example fix

# before
map f1 signal_child SIGUSR1X some-process
# after
map f1 signal_child SIGUSR1 some-process

import signal
valid = all(hasattr(signal, t.upper()) for t in 'SIGUSR1 myproc'.split() if t.startswith('SIG'))

When it happens

Trigger: A map action like `signal_child SIGUSR1 foo` where the signal name is misspelled or not available on the platform (e.g. SIGWINCH variants, case typos like SIGUSR1X). The parser does getattr(signal, token.upper()) and gets AttributeError for each unrecognized token.

Common situations: Typos in kitty.conf signal names, using Linux-only signal names on macOS/BSD, or copy-pasting configs between platforms with different signal availability.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid change_font_size specification: {rest}, treating it
• clear_terminal needs two arguments, using defaults
• {action} is unknown for clear_terminal, using reset
• Ignoring invalid paste string:
• Invalid neighbor specification: {rest}

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