jesseduffield/lazygit · error

Unrecognized key '%s' for custom command. For permitted valu

Error message

Unrecognized key '%s' for custom command. For permitted values see %s

What it means

Raised by validateCustomCommandKey in pkg/config/user_config_validation.go. Each custom command's `key` field is a Keybinding ([]string after unmarshalling); every element is checked with isValidKeybindingKey and an unrecognized key name is rejected with a docs link. Unlike error 146 this checks only customCommands entries, not the built-in keybinding tree.

Source

Thrown at pkg/config/user_config_validation.go:187

		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)
		}
	}
	return nil
}

func validateCustomCommands(customCommands []CustomCommand) error {
	for _, customCommand := range customCommands {
		if err := validateCustomCommandKey(customCommand.Key); err != nil {
			return err
		}

		if len(customCommand.CommandMenu) > 0 {
			if len(customCommand.Context) > 0 ||
				len(customCommand.Command) > 0 ||
				len(customCommand.Prompts) > 0 ||
				len(customCommand.LoadingText) > 0 ||
				len(customCommand.Output) > 0 ||

View on GitHub (pinned to c477a2959b)

Solutions

1. Rewrite the custom command's key in canonical lazygit notation (ctrl+x, alt+p, <f5>).
2. If the key is a list, check every element — the error names the exact offending one.
3. See the linked custom keybindings docs for the full label table.

Example fix

# before
customCommands:
  - key: ctrlX
    command: git status

# after
customCommands:
  - key: ctrl+x
    command: git status

for _, cc := range cfg.CustomCommands {
	for _, k := range cc.Key {
		if !validKeyRe.MatchString(k) {
			return fmt.Errorf("custom command key %q invalid", k)
		}
	}
}

When it happens

Trigger: Defining customCommands: [{key: 'ctrlX', command: ...}] where 'ctrlX' is not a valid key label — validation runs at startup right after the built-in keybinding pass.

Common situations: Users adding custom commands with ad-hoc key notation ('F1' vs '<f1>', 'ctrl-x' vs 'ctrl+x'); list-form keys where only one element is malformed.

Related errors

• Unrecognized key '%s' for custom command prompt option. For
• custom command prompt must have a type of 'input', 'menu', '
• unable to parse filter regex, error: {{err}}
• unable to parse value format, error: {{err}}
• unable to parse label format, error: {{err}}

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