junegunn/fzf · error

invalid walker option: ${str}

Error message

invalid walker option: ${str}

What it means

The walker-options parser behind --walker file,dir,hidden,follow,... (fzf 0.48+ replacement for --find and friends). Each comma token must be one of the known walker flags (file, dir, hidden, follow, and later versions add follow-logical, shell, debug); '' is explicitly ignored. Any other token returns this error.

Source

Thrown at src/options.go:1645

	return baseTheme, theme, err
}

func parseWalkerOpts(str string) (walkerOpts, error) {
	opts := walkerOpts{}
	for _, str := range strings.Split(strings.ToLower(str), ",") {
		switch str {
		case "file":
			opts.file = true
		case "dir":
			opts.dir = true
		case "hidden":
			opts.hidden = true
		case "follow":
			opts.follow = true
		case "":
			// Ignored
		default:
			return opts, errors.New("invalid walker option: " + str)
		}
	}
	if !opts.file && !opts.dir {
		return opts, errors.New("at least one of 'file' or 'dir' should be specified")
	}
	return opts, nil
}

var (
	argActionRegexp  *regexp.Regexp
	splitRegexp      *regexp.Regexp
	actionNameRegexp *regexp.Regexp
)

func firstKey(keymap map[tui.Event]string) tui.Event {
	for k := range keymap {
		return k
	}

View on GitHub (pinned to bd4efa277b)

Solutions

1. Use only known tokens: fzf --walker file,dir,hidden,follow
2. Check supported tokens for your binary: fzf --help | grep -A1 walker
3. Remove spaces after commas and plural forms
4. Upgrade fzf for newer tokens (follow-logical, shell) or drop them

Example fix

# before
fzf --walker files,folders,hidden
# after
fzf --walker file,dir,hidden

WALKER='file,dir,hidden'
IFS=',' read -ra W <<< "$WALKER"
for w in "${W[@]}"; do
  case "$w" in file|dir|hidden|follow|follow-logical|shell|debug|'') ;; *) echo "invalid walker option: $w" >&2; exit 1;; esac
done
fzf --walker "$WALKER"

isValidFzfWalkerToken() { case "$1" in file|dir|hidden|follow|follow-logical|shell|debug|'') return 0;; *) return 1;; esac; }

When it happens

Trigger: --walker files (plural), --walker file,dir,symlink (unknown token), --walker default on versions without 'default', tokens with whitespace '--walker file, dir'.

Common situations: Migrating from --file/--dir flags with different vocabulary; skim/fd option names reused; older fzf builds (pre-0.48) that lack --walker entirely report an unknown-flag error instead; version-dependent tokens like follow-logical (0.54+).

Related errors

• invalid format: ${str}
• template should include at least 1 placeholder: ${str}
• invalid algorithm (expected: v1 or v2)
• invalid border style (expected: rounded|sharp|bold|block|thi
• unsupported key: ${key}

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