Invalid change_font_size specification: {rest}, treating it

Error message

Invalid change_font_size specification: {rest}, treating it as default

What it means

The change_font_size map action requires two parts: a scope token ('all' or 'local') and an amount. When the argument string doesn't split into exactly two parts, kitty logs this and falls back to the default (True, None, 0), meaning the action effectively does nothing useful.

Source

Thrown at kitty/options/utils.py:238

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()))


@func_with_args('clear_terminal')
def clear_terminal(func: str, rest: str) -> FuncArgsType:
    vals = rest.strip().split(maxsplit=1)
    if len(vals) != 2:
        log_error('clear_terminal needs two arguments, using defaults')
        args = ['reset', True]
    else:
        action = vals[0].lower()

View on GitHub (pinned to 6d5d0c4406)

Solutions

Use the full form: change_font_size <all|local> <[+|-|*|/]number>, e.g. `map f1 change_font_size all +2`
Check for stray extra tokens after the amount

Example fix

# before
map f1 change_font_size +2
# after
map f1 change_font_size all +2

Defensive patterns

Strategy: validation

Validate before calling

import shlex
rest = 'all +2'
ok = len(rest.strip().split(maxsplit=1)) == 2 and rest.strip().split(maxsplit=1)[1][0] in '+-*/'

Prevention

Always write change_font_size as scope + signed/operated amount
Test config changes with `kitty --debug-config` or by reloading and watching stderr

When it happens

Trigger: `map f1 change_font_size all` (only one token) or extra/malformed arguments such as `map f1 change_font_size +2 extra`. The parser does rest.strip().split(maxsplit=1) and expects len == 2.

Common situations: Forgetting the +/- prefix or scope in kitty.conf, e.g. writing `change_font_size +2` without 'all'/'local'.

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

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