kovidgoyal/kitty · warning

Invalid shell integration options: {q - allowed_shell_integr

Error message

Invalid shell integration options: {q - allowed_shell_integration_values}, ignoring

What it means

shell_integration takes space-separated values from a fixed set (enabled, disabled, no-rc, no-cursor, no-title, no-prompt-mark, no-complete, no-cwd, no-sudo). Unknown tokens are reported, discarded, and if nothing valid remains the value becomes {'invalid'}.

Source

Thrown at kitty/options/utils.py:1172

        start = 1
        idx = parts[1].find('"', 1)
        if idx == -1:
            raise ValueError(f'The menu entry name in {val} must end with a double quote')
    else:
        idx = parts[1].find(' ')
        if idx == -1:
            raise ValueError(f'The menu entry {val} must have an action')
    location = ('global',) + tuple(parts[1][start:idx].split('::'))
    yield location, parts[1][idx + 1 :].lstrip()


allowed_shell_integration_values = frozenset({'enabled', 'disabled', 'no-rc', 'no-cursor', 'no-title', 'no-prompt-mark', 'no-complete', 'no-cwd', 'no-sudo'})


def shell_integration(x: str) -> frozenset[str]:
    q = frozenset(x.lower().split())
    if not q.issubset(allowed_shell_integration_values):
        log_error(f'Invalid shell integration options: {q - allowed_shell_integration_values}, ignoring')
        return q & allowed_shell_integration_values or frozenset({'invalid'})
    return q


def confirm_close(x: str) -> tuple[int, bool]:
    parts = x.split(maxsplit=1)
    num = int(parts[0])
    allow_background = len(parts) > 1 and parts[1] == 'count-background'
    return num, allow_background


def underline_exclusion(x: str) -> tuple[float, Literal['', 'px', 'pt']]:
    try:
        return float(x), ''
    except Exception:
        unit: Literal['pt', 'px'] = x[-2:]  # type: ignore
        if unit not in ('px', 'pt'):
            raise ValueError(f'Invalid underline_exclusion with unrecognized unit: {x}')

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use only supported tokens: enabled disabled no-rc no-cursor no-title no-prompt-mark no-complete no-cwd no-sudo.
2. Fix typos like no-tilte -> no-title.
3. Upgrade kitty if the flag was added in a newer release.

Example fix

# before
shell_integration no-tilte

# after
shell_integration no-title

ALLOWED = {'enabled','disabled','no-rc','no-cursor','no-title','no-prompt-mark','no-complete','no-cwd','no-sudo'}
def valid_shell_integration(x: str) -> bool:
    return set(x.lower().split()).issubset(ALLOWED)

def is_shell_integration_tokens(x: str) -> bool:
    return set(x.lower().split()) <= {'enabled','disabled','no-rc','no-cursor','no-title','no-prompt-mark','no-complete','no-cwd','no-sudo'}

When it happens

Trigger: shell_integration no-something (typo), e.g. 'no-tilte', or an unsupported token like 'sudo'.

Common situations: Typos in flags; flags from newer kitty versions used on older installs; misunderstanding that it is a space-separated list of flags, not free-form.

Related errors

• This should be run as kitten broadcast
• No option named: {k}
• No custom kitten named {kitten} found
• Not a number: {x} with error: {e}
• Not a valid unit: {x}. Allowed units are: {default_unit}, {"

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