kovidgoyal/kitty · warning

Failed to setup shell integration for: {shell}

Error message

Failed to setup shell integration for: {shell}

What it means

The shell-integration hook for the detected shell (bash/zsh/fish) raised an exception while modifying the environment; kitty logs it and continues launching without (complete) shell integration.

Source

Thrown at kitty/shell_integration.py:256

def modify_shell_environ(opts: Options, env: dict[str, str], argv: list[str]) -> None:
    shell = get_supported_shell_name(argv[0])
    ksi = get_effective_ksi_env_var(opts)
    if shell is None or not ksi:
        return
    env['KITTY_SHELL_INTEGRATION'] = ksi
    if not shell_integration_allows_rc_modification(opts):
        return
    f = ENV_MODIFIERS.get(shell)
    if f is not None:
        try:
            f(env, argv)
        except Exception:
            import traceback

            traceback.print_exc()
            log_error(f'Failed to setup shell integration for: {shell}')

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Check the printed traceback to identify which shell hook failed
2. Update kitty — shell integration bugs for specific shell versions are commonly fixed
3. Set shell_integration to a reduced set of options or disable it to silence the failure
4. Ensure the configured shell resolves to the real binary: kitty --debug-config shows the shell path

Example fix

# before
shell /opt/my-wrapper/bash

# after
shell /bin/bash

When it happens

Trigger: Any exception from the per-shell f(env, argv) function in modify_shell_environ, e.g. unexpected argv shape or a missing expected binary.

Common situations: Unusual shell wrappers/paths (custom bash via Nix/homebrew), kitty version changes to shell integration logic, or PATH issues where the real shell binary can't be located.

Related errors

• {path} is not a supported shell
• Failed to find libxkbcommon
• line.decode('utf-8', 'replace').rstrip()
• Failed to find the kitty executable, this kitten requires th
• could not connect to session D-Bus: %s

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