kovidgoyal/kitty · error · ValueError

is not a valid disable ligatures strategy

Error message

{strategy} is not a valid disable ligatures strategy

What it means

disable_ligatures_in validates the strategy (second token, or first when only one is given) against never, always, cursor. Anything else raises ValueError naming the invalid strategy.

Solutions

  1. Use never, always, or cursor as the strategy
  2. Remember order: where (optional) then strategy
  3. Fix typos like 'curser'

Example fix

# before
disable_ligatures all on
# after
disable_ligatures all always
Defensive patterns

Strategy: validation

Validate before calling

parts = rest.split(maxsplit=1)
where, strategy = ('active', parts[0]) if len(parts) == 1 else parts
if strategy not in ('never','always','cursor'):
    raise SystemExit(f'bad strategy: {strategy}')

Type guard

def is_ligature_strategy(v: str) -> bool:
    return v in ('never','always','cursor')

Prevention

When it happens

Trigger: `disable_ligatures all sometimes`, `disable_ligatures off`, or `disable_ligatures active on` — the strategy token is not one of never/always/cursor.

Common situations: Boolean-style values (on/off); misspelling 'cursor'; older kitty versions had different strategy names so shared dotfiles break on upgrade.

Related errors

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

Appendix: source

Thrown at kitty/options/utils.py:412

    mult = 1
    sleep_time = sleep_time or '1'
    if sleep_time[-1] in 'shmd':
        mult = {'s': 1, 'm': 60, 'h': 3600, 'd': 24 * 3600}[sleep_time[-1]]
        sleep_time = sleep_time[:-1]
    return func, [abs(float(sleep_time)) * mult]


@func_with_args('disable_ligatures_in')
def disable_ligatures_in(func: str, rest: str) -> FuncArgsType:
    parts = rest.split(maxsplit=1)
    if len(parts) == 1:
        where, strategy = 'active', parts[0]
    else:
        where, strategy = parts
    if where not in ('active', 'all', 'tab'):
        raise ValueError(f'{where} is not a valid set of windows to disable ligatures in')
    if strategy not in ('never', 'always', 'cursor'):
        raise ValueError(f'{strategy} is not a valid disable ligatures strategy')
    return func, [where, strategy]


@func_with_args('layout_action')
def layout_action(func: str, rest: str) -> FuncArgsType:
    parts = rest.split(maxsplit=1)
    if not parts:
        raise ValueError('layout_action must have at least one argument')
    return func, [parts[0], tuple(parts[1:])]


def parse_marker_spec(ftype: str, parts: Sequence[str]) -> tuple[str, str | tuple[tuple[int, str], ...], int]:
    flags = re.UNICODE
    if ftype in ('text', 'itext', 'regex', 'iregex'):
        if ftype.startswith('i'):
            flags |= re.IGNORECASE
        if not parts or len(parts) % 2 != 0:
            raise ValueError('Mark group number and text/regex are not specified in pairs: {}'.format(' '.join(parts)))

View on GitHub (pinned to 6d5d0c4406)