What causes "key name required" in junegunn/fzf?

Inspect the --bind string for leading/trailing/doubled commas and remove them

key name required

Error message

key name required

What it means

Thrown by parseKeymap while parsing --bind. Each comma-separated pair must be 'key:action'; a pair whose key part (before the colon) is empty — e.g. a leading or doubled comma — fails this check. The message is also reused by parseKeyChords callers like --bind-toggle-sort.

Source

Thrown at src/options.go:2028

			}
		}
		prevSpec = ""
	}
	return actions, nil
}

func parseKeymap(keymap map[tui.Event][]*action, str string) error {
	var err error
	masked := maskActionContents(str)
	idx := 0
	keys := []string{}
	for _, pairStr := range strings.Split(masked, ",") {
		origPairStr := str[idx : idx+len(pairStr)]
		idx += len(pairStr) + 1

		pair := strings.SplitN(pairStr, ":", 2)
		if len(pair[0]) == 0 {
			return errors.New("key name required")
		}
		keys = append(keys, pair[0])
		if len(pair) < 2 {
			continue
		}
		for _, keyName := range keys {
			var key tui.Event
			if len(keyName) == 1 && keyName[0] == escapedColon {
				key = tui.Key(':')
			} else if len(keyName) == 1 && keyName[0] == escapedComma {
				key = tui.Key(',')
			} else if len(keyName) == 1 && keyName[0] == escapedPlus {
				key = tui.Key('+')
			} else {
				keys, _, err := parseKeyChords(keyName, "key name required")
				if err != nil {
					return err
				}

View on GitHub (pinned to bd4efa277b)

Solutions

Inspect the --bind string for leading/trailing/doubled commas and remove them
When composing bind lists in scripts, filter out empty entries before joining
Quote shell variables and provide defaults so empty fragments never reach --bind

Example fix

# before
EXTRA=""
fzf --bind "ctrl-a:accept,$EXTRA"
# after
BINDS="ctrl-a:accept${EXTRA:+,$EXTRA}"
fzf --bind "$BINDS"

Defensive patterns

Strategy: validation

Validate before calling

# bash: reject empty key segments before passing to --bind
bind_clean() {
  printf '%s' "$1" | awk -F, 'BEGIN{ok=1} {for(i=1;i<=NF;i++) if ($i ~ /^([^:]*):.+/) continue; else if ($i=="") continue; else ok=0} END{exit !ok}'
}
# simpler: drop empty fragments when composing
IFS=',' read -ra PARTS <<< "$BINDS"
FILTERED=$(printf '%s' "${PARTS[@]}" | grep -v '^$')

Prevention

Use ${VAR:+,$VAR} expansion when appending optional bind fragments
Never leave bare leading/trailing commas in composed --bind strings

When it happens

Trigger: `--bind ',ctrl-f:refresh'` (leading comma), `--bind 'ctrl-a:accept,,ctrl-b:cancel'` (doubled comma), or `--bind ':accept'` (empty key). Also from parseToggleSort when the --bind-toggle-sort key string is empty.

Common situations: Programmatically building bind strings and joining with commas even when one entry is empty; trailing comma left by a shell variable that expands to nothing: `--bind "ctrl-a:accept,$EXTRA_BIND"` with EXTRA_BIND unset.

Related errors

AI-assisted analysis of junegunn/fzf@bd4efa277b (2026-08-15). Data as JSON: /api/errors/0a27b6fd0391581f. Report an issue: GitHub.