junegunn/fzf · error

empty jump labels

Error message

empty jump labels

What it means

fzf requires the --jump-labels charset to be non-empty; the labels are the characters used for jump mode (--bind jump), so an empty set makes jumping impossible. The check at options.go:3525 fires when len(opts.JumpLabels) == 0.

Source

Thrown at src/options.go:3525

	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 {
		return errors.New("scroll offset must be a non-negative integer")
	}

	if opts.Tabstop < 1 {
		return errors.New("tab stop must be a positive integer")
	}

	if len(opts.JumpLabels) == 0 {
		return errors.New("empty jump labels")
	}

	if opts.FreezeLeft < 0 || opts.FreezeRight < 0 {
		return errors.New("number of fields to freeze must be a non-negative integer")
	}

	if validateJumpLabels {
		for _, r := range opts.JumpLabels {
			if r < 32 || r > 126 {
				return errors.New("non-ascii jump labels are not allowed")
			}
		}
	}
	return err
}

func applyPreset(opts *Options, preset string) error {
	// Reset to the platform default

View on GitHub (pinned to bd4efa277b)

Solutions

1. Provide at least one printable ASCII label (default is ascii)
2. Omit --jump-labels to use the default set
3. Guard templated values so empty strings fall back to the default

Example fix

# before
fzf --jump-labels=''
# after
fzf --jump-labels=abcdefghijklmnopqrstuvwxyz

// Shell: fall back to default when empty
[ -n "$labels" ] || labels='ascii'
exec fzf --jump-labels="$labels"

func validJumpLabels(s string) bool { return len([]rune(s)) > 0 }

When it happens

Trigger: Passing --jump-labels='' (explicitly empty). The option was recognized and applied, leaving an empty label list, which the post-parse validation rejects.

Common situations: Scripts templating the label string from a variable that is sometimes empty; attempting to 'reset' labels by passing an empty string instead of omitting the flag.

Related errors

• non-ascii jump labels are not allowed
• unknown action: ${spec}
• invalid layout (expected: default / reverse / reverse-list)
• invalid info style (expected: default|right|hidden|inline[-r
• history max must be a positive integer

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