junegunn/fzf · error

$FZF_DEFAULT_OPTS: %s

Error message

$FZF_DEFAULT_OPTS: %s

What it means

The $FZF_DEFAULT_OPTS environment variable could not be tokenized: its string content has a shell-word syntax error such as an unterminated quote. This is the string counterpart of error 61 and aborts startup before command-line arguments are considered.

Source

Thrown at src/options.go:3931

			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())
		}
		if len(words) > 0 {
			if err := parseOptions(&index, opts, words); err != nil {
				return nil, errors.New("$FZF_DEFAULT_OPTS: " + err.Error())
			}
		}
	}

	// 3. Options from command-line arguments
	if err := parseOptions(&index, opts, args); err != nil {
		return nil, err
	}

	// 4. Change default scheme when built-in walker is used
	if len(opts.Scheme) == 0 {
		opts.Scheme = "default"
		if len(opts.Criteria) == 0 {
			// NOTE: Let's assume $FZF_DEFAULT_COMMAND generates a list of file paths.

View on GitHub (pinned to bd4efa277b)

Solutions

1. Inspect the variable: printf '%s\n' "$FZF_DEFAULT_OPTS"
2. Rebalance the quoting, usually by wrapping the preview command in double quotes and inner paths in single quotes
3. Move complex options into $FZF_DEFAULT_OPTS_FILE where quoting is easier to get right

Example fix

# before
export FZF_DEFAULT_OPTS="--preview 'head -100 {}"
# after
export FZF_DEFAULT_OPTS="--preview 'head -100 {}'"

# smoke-test the variable tokenizes as shell words
if [ -n "$FZF_DEFAULT_OPTS" ]; then
  eval "set -- $FZF_DEFAULT_OPTS" 2>/dev/null || { echo 'FZF_DEFAULT_OPTS has bad quoting' >&2; exit 1; }
fi

When it happens

Trigger: FZF_DEFAULT_OPTS contains an unbalanced quote or bad escape, so parseShellWords(os.Getenv("FZF_DEFAULT_OPTS")) fails.

Common situations: Complex exports in .bashrc/.zshrc where nested quoting for a --preview command goes wrong; values built by concatenation that lose a closing quote; copy-pasted shell lines with smart quotes.

Related errors

• $FZF_DEFAULT_OPTS_FILE: %s
• %s: %s
• failed to open %s
• permission denied: ${path}
• invalid history file: ${e.Error()}

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