Unrecognized key '%s' for keybinding '%s'. For permitted val

Error message

Unrecognized key '%s' for keybinding '%s'. For permitted values see %s

What it means

Raised by validateKeybindingsRecurse in pkg/config/user_config_validation.go. After config parsing, the whole KeybindingConfig tree is walked via reflection; every string leaf is checked against isValidKeybindingKey and anything unrecognized (wrong key name, wrong separator form, typo like <c-x> vs <c-x> variants or 'ctrlX') is rejected with a link to the custom keybindings docs.

Source

Thrown at pkg/config/user_config_validation.go:171

			} else {
				newPath = fmt.Sprintf("%s.%s", path, field.Name)
			}
			if err := validateKeybindingsRecurse(newPath,
				value.FieldByName(field.Name).Interface()); err != nil {
				return err
			}
		}
	} else if value.Kind() == reflect.Slice {
		for i := range value.Len() {
			if err := validateKeybindingsRecurse(
				fmt.Sprintf("%s[%d]", path, i), value.Index(i).Interface()); err != nil {
				return err
			}
		}
	} else if value.Kind() == reflect.String {
		key := node.(string)
		if !isValidKeybindingKey(key) {
			return fmt.Errorf("Unrecognized key '%s' for keybinding '%s'. For permitted values see %s",
				key, path, constants.Links.Docs.CustomKeybindings)
		}
	} else {
		log.Fatalf("Unexpected type for property '%s': %s", path, value.Kind())
	}
	return nil
}

func validateKeybindings(keybindingConfig KeybindingConfig) error {
	return validateKeybindingsRecurse("", keybindingConfig)
}

func validateCustomCommandKey(key Keybinding) error {
	for _, k := range key {
		if !isValidKeybindingKey(k) {
			return fmt.Errorf("Unrecognized key '%s' for custom command. For permitted values see %s",
				k, constants.Links.Docs.CustomKeybindings)
		}

View on GitHub (pinned to c477a2959b)

Solutions

Rewrite the offending key using lazygit's notation as documented at constants.Links.Docs.CustomKeybindings (e.g. ctrl+q, alt+z, <c-u>, <pagedown>).
Check for missing '+' or angle brackets and stray whitespace.
If the key seems legitimate, verify it exists in lazygit's key label table for your version and update if needed.

Example fix

# before
keybinding:
  universal:
    quit: ctrlq

# after
keybinding:
  universal:
    quit: ctrl+q

Defensive patterns

Strategy: validation

Validate before calling

// lazygit exposes the same check; in your own tooling keep a copy of the label table:
var validKeyRe = regexp.MustCompile(`^(ctrl|alt|cmd)\+[a-z]$|^[a-zA-Z0-9]$|^<f[0-9]+>$`)
if !validKeyRe.MatchString(key) {
	return fmt.Errorf("suspicious keybinding value: %q", key)
}

Prevention

Use ctrl+x / alt+x / <f1> notation consistently.
Diff your keybindings section after lazygit upgrades; label tables change between versions.
Keep the docs link from the error handy — it lists every permitted label.

When it happens

Trigger: Any string under the keybinding section of the user config that isValidKeybindingKey does not accept — e.g. `universal.quit: ctrlq` instead of `ctrl+q`, or a key name not in lazygit's key label table — triggers this at startup validation.

Common situations: Migrating keybindings from other tools (vim/emacs notation); typos in '+' separators; keys supported only on some terminals or newer versions; copy-pasting from outdated docs.

Related errors

AI-assisted analysis of jesseduffield/lazygit@c477a2959b (2026-08-15). Data as JSON: /api/errors/219f51b686ff471d. Report an issue: GitHub.