What causes "invalid algorithm (expected: v1 or v2)" in junegunn/fzf?

Use exactly v1 or v2 (lowercase): fzf --algo v2

invalid algorithm (expected: v1 or v2)

Error message

invalid algorithm (expected: v1 or v2)

What it means

parseAlgo maps the --algo flag to a fuzzy matcher implementation. Only 'v1' (original fzf algorithm) and 'v2' (fzf 0.15+ default, better scoring) are accepted; anything else — including legacy names like 'v3', typos, or empty strings — returns this error.

Source

Thrown at src/options.go:960

	return Delimiter{regex: rx}
}

func isAlphabet(char uint8) bool {
	return char >= 'a' && char <= 'z'
}

func isNumeric(char uint8) bool {
	return char >= '0' && char <= '9'
}

func parseAlgo(str string) (algo.Algo, error) {
	switch str {
	case "v1":
		return algo.FuzzyMatchV1, nil
	case "v2":
		return algo.FuzzyMatchV2, nil
	}
	return nil, errors.New("invalid algorithm (expected: v1 or v2)")
}

func parseBorder(str string, optional bool) (tui.BorderShape, error) {
	switch str {
	case "line":
		return tui.BorderLine, nil
	case "inline":
		return tui.BorderInline, nil
	case "rounded":
		return tui.BorderRounded, nil
	case "sharp":
		return tui.BorderSharp, nil
	case "bold":
		return tui.BorderBold, nil
	case "block":
		return tui.BorderBlock, nil
	case "thinblock":
		return tui.BorderThinBlock, nil

View on GitHub (pinned to bd4efa277b)

Solutions

Use exactly v1 or v2 (lowercase): fzf --algo v2
Remove the --algo flag entirely to get the default (v2)
Grep your shell rc files: grep -Rn 'algo' ~/.bashrc ~/.zshrc ~/.config/fzf
If a different matcher is wanted, use --exact or --scheme instead of inventing --algo values

Example fix

# before
export FZF_DEFAULT_OPTS='--algo fuzzy'
# after
export FZF_DEFAULT_OPTS='--algo v2'

Defensive patterns

Strategy: validation

Validate before calling

case "${ALGO:=v2}" in v1|v2) ;; *) echo "invalid --algo: $ALGO" >&2; exit 1;; esac
fzf --algo "$ALGO"

Type guard

isValidFzfAlgo() { case "$1" in v1|v2) return 0;; *) return 1;; esac; }

Prevention

Whitelist --algo to {v1, v2} at the point of configuration
Omit --algo unless you specifically need v1 behavior
grep your rc files after upgrading fzf to catch stale algorithm names

When it happens

Trigger: fzf --algo v3, --algo=V2 (uppercase not matched), --algo '' from an unset exported FZF_DEFAULT_OPTS="--algo $ALGO" with ALGO empty, or scripts written against third-party forks that accept other algorithm names.

Common situations: Shell profiles exporting FZF_DEFAULT_OPTS with a typo'd algorithm; copy-pasted dotfiles referencing algorithms from skim/fzy ('fzy', 'clangd'); version drift where a user assumes a 'v3' exists.

Related errors

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