junegunn/fzf · error

unknown action: ${spec}

Error message

unknown action: ${spec}

What it means

Thrown while parsing a --bind action list. After all known action names are exhausted, the token is matched against execute-style actions (execute(...), execute-silent(...), reload(...), etc. via isExecuteAction); if that also fails and the token is not the empty first token (multi-key continuation) or 'change-multi', it is an unknown action and parsing aborts.

Source

Thrown at src/options.go:1979

		case "wait":
			appendAction(actWait)
		case "bell":
			appendAction(actBell)
		case "exclude":
			appendAction(actExclude)
		case "exclude-multi":
			appendAction(actExcludeMulti)
		case "bg-cancel":
			appendAction(actBgCancel)
		default:
			t := isExecuteAction(specLower)
			if t == actIgnore {
				if specIndex == 0 && specLower == "" {
					actions = append(prevActions, actions...)
				} else if specLower == "change-multi" {
					appendAction(actChangeMulti)
				} else {
					return nil, errors.New("unknown action: " + spec)
				}
			} else {
				offset := len(actionNameRegexp.FindString(spec))
				var actionArg string
				if spec[offset] == ':' {
					if specIndex == len(originalStrings)-1 {
						actionArg = spec[offset+1:]
						actions = append(actions, &action{t: t, a: actionArg})
					} else {
						prevSpec = spec + "+"
						continue
					}
				} else {
					actionArg = spec[offset+1 : len(spec)-1]
					actions = append(actions, &action{t: t, a: actionArg})
				}
				switch t {
				case actUnbind, actRebind, actToggleBind:

View on GitHub (pinned to bd4efa277b)

Solutions

1. Check the action name against `fzf --man` (MANPAGE section ACTIONS) and fix the typo
2. Confirm the action exists in your fzf version: `fzf --version`; upgrade fzf if the action is newer
3. For execute actions, verify the full execute(...) syntax is used, since a bare prefix is not an action name

Example fix

# before
fzf --bind 'ctrl-f:refrsh-preview'
# after
fzf --bind 'ctrl-f:refresh-preview'

# bash: check action name against the binary's own list before use
action_ok() {
  fzf --man 2>/dev/null | grep -qE "(^|[[:space:]])${1}(:|$)"
}
action_ok refresh-preview || { echo "bad action" >&2; exit 1; }

When it happens

Trigger: `--bind 'ctrl-f:foobar'`, a misspelled action like `--bind 'ctrl-f:refrsh'`, or an action name from a newer/older fzf version than the one in use (e.g. 'change-multi' on an old build).

Common situations: Typos in bind specs; copy-pasting bind lines from blog posts or fzf wiki pages targeting a different fzf version; trailing whitespace/case issues since the spec is matched case-insensitively but must still be a real action name.

Related errors

• unable to put non-printable character
• key name required
• bind action not specified: ${keys}
• multiple keys specified
• invalid layout (expected: default / reverse / reverse-list)

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