kovidgoyal/kitty · error · ValueError

allow_fallback values must be a subset of shifted, ascii, go

Error message

allow_fallback values must be a subset of shifted, ascii, got: {val}

What it means

The allow_fallback key-map option accepts only '', 'none', 'ascii', or 'ascii,shifted' (via a match statement); any other string raises this ValueError.

Source

Thrown at kitty/options/utils.py:1508

KeyboardModeMap = dict[str, KeyboardMode]
key_map_option_converters: defaultdict[str, Callable[[str], Any]] = defaultdict(lambda: lambda x: x)
key_map_option_converters['timeout'] = float


def _convert_allow_fallback(val: str) -> tuple[KeyFallbackType, ...]:
    match val:
        case 'shifted,ascii':
            return (KeyFallbackType.shifted, KeyFallbackType.alternate)
        case 'shifted':
            return (KeyFallbackType.shifted,)
        case '' | 'none':
            return ()
        case 'ascii,shifted':
            return (KeyFallbackType.alternate, KeyFallbackType.shifted)
        case 'ascii':
            return (KeyFallbackType.alternate,)
    raise ValueError(f'allow_fallback values must be a subset of shifted, ascii, got: {val}')


key_map_option_converters['allow_fallback'] = _convert_allow_fallback


def parse_options_for_map(val: str) -> tuple[KeyMapOptions, str]:
    expecting_arg = ''
    ans = KeyMapOptions()
    s = Shlex(val)
    while (tok := s.next_word())[0] > -1:
        x = tok[1]
        if expecting_arg:
            object.__setattr__(ans, expecting_arg, key_map_option_converters[expecting_arg](x))
            expecting_arg = ''
        elif x.startswith('--'):
            expecting_arg = x[2:]
            k, sep, v = expecting_arg.partition('=')
            k = k.replace('-', '_')

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Use exactly one of: (empty), none, ascii, or ascii,shifted
2. Write the combined value in the exact order 'ascii,shifted'

Example fix

# before
map --allow-fallback=shifted f1 copy_to_clipboard
# after
map --allow-fallback=ascii,shifted f1 copy_to_clipboard

def valid_allow_fallback(v: str) -> bool:
    return v in ('', 'none', 'ascii', 'ascii,shifted')

When it happens

Trigger: Passing '--allow-fallback=shifted' (unsupported order), '--allow-fallback=all', or any unrecognized combination in a map line.

Common situations: Assuming any subset order works; the parser literally matches only the three exact strings plus empty/none.

Related errors

• The value {x} is not a known choice
• The value {val} is not a valid choice for progress_bar
• The value {val} is not a valid choice for scrollbar
• The value {val} is not a valid choice for strip_trailing_spa
• The value {val} is not a valid choice for tab_bar_align

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