kovidgoyal/kitty · error · ValueError

{spec} is not a valid setting

Error message

{spec} is not a valid setting

What it means

parse_spacing_settings expects each argument in the form name=value (e.g. margin=10 or padding-left=default). Anything without exactly one '=' raises ValueError '{spec} is not a valid setting'.

Source

Thrown at kitty/rc/set_spacing.py:50

        which, edge = k.lower().split('-', 1)
        q = f'window_{which}_width'
        new_edges = getattr(opts, q)._replace(**{edge: val})
        setattr(opts, q, new_edges)


def parse_spacing_settings(args: Iterable[str]) -> dict[str, float | None]:
    mapper: dict[str, list[LiteralString]] = {}
    for q in ('margin', 'padding'):
        mapper[q] = f'{q}-left {q}-top {q}-right {q}-bottom'.split()
        mapper[f'{q}-h'] = mapper[f'{q}-horizontal'] = f'{q}-left {q}-right'.split()
        mapper[f'{q}-v'] = mapper[f'{q}-vertical'] = f'{q}-top {q}-bottom'.split()
        for edge in ('left', 'top', 'right', 'bottom'):
            mapper[f'{q}-{edge}'] = [f'{q}-{edge}']
    settings: dict[str, float | None] = {}
    for spec in args:
        parts = spec.split('=', 1)
        if len(parts) != 2:
            raise ValueError(f'{spec} is not a valid setting')
        which = mapper.get(parts[0].lower())
        if not which:
            raise ValueError(f'{parts[0]} is not a valid edge specification')
        if parts[1].lower() == 'default':
            val = None
        else:
            try:
                val = float(parts[1])
            except Exception:
                raise ValueError(f'{parts[1]} is not a number')
        for q in which:
            settings[q] = val
    return settings


class SetSpacing(RemoteCommand):
    protocol_spec = __doc__ = """
    settings+/dict.spacing: An object mapping margins/paddings using canonical form {'margin-top': 50, 'padding-left': null} etc

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Include a value: name=value, e.g. 'margin=20' or 'cell-height=default'
2. Quote the whole spec so the shell passes it as one argument

Example fix

# before
kitten @set-spacing padding
# after
kitten @set-spacing padding=12

def valid_spec(s): return '=' in s and len(s.split('=',1))==2

def is_spacing_spec(s: str) -> bool: return len(s.split('=',1)) == 2

When it happens

Trigger: Passing a spacing spec without '=' such as 'kitten @set-spacing margin' or 'padding'.

Common situations: Shell quoting mistakes or forgetting the =value part in launch/set-spacing arguments.

Related errors

• {parts[0]} is not a valid edge specification
• {parts[1]} is not a number
• No colors specified
• Unknown type_of_input: {type_of_input}
• Unknown keys in multicell_command:

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