junegunn/fzf · error

at most 3 tiebreaks are allowed: ${str}

Error message

at most 3 tiebreaks are allowed: ${str}

What it means

After parsing, parseTiebreak verifies the criteria slice (which always starts with the implicit byScore) has at most 4 entries — i.e. at most 3 user-specified tiebreaks. A longer list returns this error with the original --tiebreak string.

Source

Thrown at src/options.go:1403

				return nil, err
			}
			criteria = append(criteria, byLength)
		case "begin":
			if err := check(&hasBegin, "begin"); err != nil {
				return nil, err
			}
			criteria = append(criteria, byBegin)
		case "end":
			if err := check(&hasEnd, "end"); err != nil {
				return nil, err
			}
			criteria = append(criteria, byEnd)
		default:
			return nil, errors.New("invalid sort criterion: " + str)
		}
	}
	if len(criteria) > 4 {
		return nil, errors.New("at most 3 tiebreaks are allowed: " + str)
	}
	return criteria, nil
}

func dupeTheme(theme *tui.ColorTheme) *tui.ColorTheme {
	dupe := *theme
	return &dupe
}

func parseTheme(defaultTheme *tui.ColorTheme, str string) (*tui.ColorTheme, *tui.ColorTheme, error) {
	var err error
	var baseTheme *tui.ColorTheme
	theme := dupeTheme(defaultTheme)
	rrggbb := regexp.MustCompile("^#[0-9a-fA-F]{6}$")
	comma := regexp.MustCompile(`[\s,]+`)
	for _, str := range comma.Split(strings.ToLower(str), -1) {
		str = strings.TrimSpace(str)
		if len(str) == 0 {

View on GitHub (pinned to bd4efa277b)

Solutions

1. Trim to at most 3 criteria: --tiebreak chunk,length,begin
2. If full determinism is needed, put index last and drop weaker criteria: --tiebreak length,index

Example fix

# before
fzf --tiebreak chunk,length,begin,end
# after
fzf --tiebreak chunk,length,begin

IFS=',' read -ra C <<< "$TB"
[ "${#C[@]}" -le 3 ] || { echo 'at most 3 tiebreaks allowed' >&2; exit 1; }
fzf --tiebreak "$TB"

When it happens

Trigger: --tiebreak chunk,length,begin,end,pathname (5 tokens), --tiebreak length,begin,end,pathname (4 tokens > 3 allowed).

Common situations: Kitchen-sink configs trying to fully determinize ordering; options accumulated across FZF_DEFAULT_OPTS and an explicit CLI flag; scripted lists grown over time.

Related errors

• duplicate sort criteria: ${name}
• index should be the last criterion
• invalid sort criterion: ${str}
• invalid format: ${str}
• template should include at least 1 placeholder: ${str}

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