junegunn/fzf · error

unknown option: %s

Error message

unknown option: %s

What it means

The given argument did not match any known option in this parsing branch. This block handles the small/short option chain (-n, -s, -m, delimiter, etc.); when an argument matches none of the recognized forms, fzf reports it as an unknown option instead of silently ignoring it.

Source

Thrown at src/options.go:3498

		default:
			if match, value := optString(arg, "-q"); match {
				opts.Query = value
			} else if match, value := optString(arg, "-f"); match {
				opts.Filter = &value
			} else if match, value := optString(arg, "-d"); match {
				opts.Delimiter = delimiterRegexp(value)
			} else if match, value := optString(arg, "-n"); match {
				if opts.Nth, err = splitNth(value); err != nil {
					return err
				}
			} else if match, _ := optString(arg, "-s"); match {
				opts.Sort = 1 // Don't care
			} else if match, value := optString(arg, "-m"); match {
				if opts.Multi, err = atoi(value); err != nil {
					return err
				}
			} else {
				return errors.New("unknown option: " + arg)
			}
		}

		if val != nil {
			return errors.New("unexpected value for " + arg + ": " + *val)
		}
	}
	*index += len(allArgs)

	if opts.HeaderLines < 0 {
		return errors.New("header lines must be a non-negative integer")
	}

	if opts.HscrollOff < 0 {
		return errors.New("hscroll offset must be a non-negative integer")
	}

	if opts.ScrollOff < 0 {

View on GitHub (pinned to bd4efa277b)

Solutions

1. Check spelling of the option against fzf --help
2. Use the long form of the option (e.g. --multi instead of -m) which gives clearer errors
3. Pass each short option separately rather than bundling them
4. Upgrade fzf if the option was added in a newer version

Example fix

# before
fzf -sort
# after
fzf --sort

// Shell: reject unknown short flags before calling fzf
known='d D e m N n s x q t Q + --'
for a in "$@"; do
  case "$a" in -*) [[ $known == *"${a%%=*}"* ]] || { echo "unsupported flag: $a" >&2; exit 2; } ;; esac
done
exec fzf "$@"

Capture fzf's stderr; on 'unknown option:', echo the offending token and suggest `fzf --help` in your wrapper's error path.

When it happens

Trigger: Passing an unrecognized short option or a misspelled flag to fzf, e.g. -x, -sort, or -N (uppercase). Each else-if attempts optString(arg, ...) for known short options; falling through all of them reaches errors.New("unknown option: " + arg) at options.go:3498.

Common situations: Typos in short flags; using flags from a different tool's muscle memory (grep/awk style); passing combined short options like -sm which fzf does not support in this form; version differences where an option was renamed.

Related errors

• unexpected value for %s: %s
• unsupported style preset: %s
• at least one of 'file' or 'dir' should be specified
• unable to put non-printable character
• unknown action: ${spec}

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