What causes "$FZF_DEFAULT_OPTS_FILE: %s" in junegunn/fzf?

Check the variable points to an existing readable file: echo $FZF_DEFAULT_OPTS_FILE && cat "$FZF_DEFAULT_OPTS_FILE"

$FZF_DEFAULT_OPTS_FILE: %s

Error message

$FZF_DEFAULT_OPTS_FILE: %s

What it means

fzf failed to read the file pointed to by the $FZF_DEFAULT_OPTS_FILE environment variable. The file is read before any other option source, so a broken path aborts startup entirely. The underlying OS error (e.g. 'no such file or directory', 'permission denied') is appended after the prefix.

Source

Thrown at src/options.go:3914

}

func parseShellWords(str string) ([]string, error) {
	parser := shellwords.NewParser()
	parser.ParseComment = true
	return parser.Parse(str)
}

// ParseOptions parses command-line options
func ParseOptions(useDefaults bool, args []string) (*Options, error) {
	opts := defaultOptions()
	index := 0

	if useDefaults {
		// 1. Options from $FZF_DEFAULT_OPTS_FILE
		if path := os.Getenv("FZF_DEFAULT_OPTS_FILE"); path != "" {
			bytes, err := os.ReadFile(path)
			if err != nil {
				return nil, errors.New("$FZF_DEFAULT_OPTS_FILE: " + err.Error())
			}

			words, parseErr := parseShellWords(string(bytes))
			if parseErr != nil {
				return nil, errors.New(path + ": " + parseErr.Error())
			}
			if len(words) > 0 {
				if err := parseOptions(&index, opts, words); err != nil {
					return nil, errors.New(path + ": " + err.Error())
				}
			}
		}

		// 2. Options from $FZF_DEFAULT_OPTS string
		words, parseErr := parseShellWords(os.Getenv("FZF_DEFAULT_OPTS"))
		if parseErr != nil {
			return nil, errors.New("$FZF_DEFAULT_OPTS: " + parseErr.Error())
		}

View on GitHub (pinned to bd4efa277b)

Solutions

Check the variable points to an existing readable file: echo $FZF_DEFAULT_OPTS_FILE && cat "$FZF_DEFAULT_OPTS_FILE"
Fix the path in your shell rc file, or unset the variable if the file is no longer needed
Verify permissions: the file must be readable by the user running fzf (chmod u+r)

Example fix

# before
export FZF_DEFAULT_OPTS_FILE=~/.config/fzf/opts   # wrong path
# after
export FZF_DEFAULT_OPTS_FILE="$HOME/.config/fzf/opts"
# or remove it if unused
unset FZF_DEFAULT_OPTS_FILE

Defensive patterns

Strategy: validation

Validate before calling

# before starting fzf
if [ -n "$FZF_DEFAULT_OPTS_FILE" ] && [ ! -r "$FZF_DEFAULT_OPTS_FILE" ]; then
  echo "FZF_DEFAULT_OPTS_FILE unreadable: $FZF_DEFAULT_OPTS_FILE" >&2
  unset FZF_DEFAULT_OPTS_FILE
fi
fzf

Prevention

Export FZF_DEFAULT_OPTS_FILE only after verifying the file exists in the same rc block
Point it at a file inside a directory you own and version-control it with your dotfiles

When it happens

Trigger: ParseOptions(useDefaults=true, args) is called (normal fzf startup) and $FZF_DEFAULT_OPTS_FILE is set to a path that os.ReadFile cannot read: missing file, dangling symlink, directory, or unreadable permissions.

Common situations: Shell rc files exporting a stale path after the file was moved or deleted; typos in the export line; pointing at a file on an unmounted volume; CI containers where the dotfile was never copied in.

Related errors

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