kovidgoyal/kitty · warning

Invalid neighbor specification: {rest}

Error message

Invalid neighbor specification: {rest}

What it means

The neighboring_window action received a direction that isn't left/right/top/bottom (after mapping up->top, down->bottom). kitty falls back to 'right'.

Source

Thrown at kitty/options/utils.py:289

    return func, [rest]


@func_with_args('paste')
def paste_parse(func: str, rest: str) -> FuncArgsType:
    text = ''
    try:
        text = defines.expand_ansi_c_escapes(rest)
    except Exception:
        log_error('Ignoring invalid paste string: ' + rest)
    return func, [text]


@func_with_args('neighboring_window')
def neighboring_window(func: str, rest: str) -> FuncArgsType:
    rest = rest.lower()
    rest = {'up': 'top', 'down': 'bottom'}.get(rest, rest)
    if rest not in ('left', 'right', 'top', 'bottom'):
        log_error(f'Invalid neighbor specification: {rest}')
        rest = 'right'
    return func, [rest]


@func_with_args('resize_window')
def resize_window(func: str, rest: str) -> FuncArgsType:
    vals = rest.strip().split(maxsplit=1)
    if len(vals) > 2:
        log_error('resize_window needs one or two arguments, using defaults')
        args = ['wider', 1]
    else:
        quality = vals[0].lower()
        if quality not in ('reset', 'taller', 'shorter', 'wider', 'narrower'):
            log_error(f'Invalid quality specification: {quality}')
            quality = 'wider'
        increment = 1
        if len(vals) == 2:
            try:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use one of: left, right, top, bottom (up/down are accepted aliases)
2. Fix typos in the direction argument

Example fix

# before
map f1 neighboring_window up-left
# after
map f1 neighboring_window up

d = 'up'
alias = {'up':'top','down':'bottom'}.get(d, d)
ok = alias in ('left','right','top','bottom')

When it happens

Trigger: `map f1 neighboring_window up-left` or any token outside the four valid directions; also plain typos like 'rigth'.

Common situations: Assuming diagonal or other directions exist; misspelling a direction in kitty.conf.

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

• Unknown signal: {rest} ignoring
• 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:

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