charmbracelet/gum · error

no options provided, see `gum filter --help`

Error message

no options provided, see `gum filter --help`

What it means

gum filter sources its candidate list from flags/args, stdin, or (with --fuzzy over the filesystem) files.List(). If all sources yield an empty list, Run fails fast with this pointer to `gum filter --help` rather than showing an empty filter prompt.

Source

Thrown at filter/command.go:50

	styles.Blurred.Prompt = o.PromptStyle.ToLipgloss()
	styles.Focused.Placeholder = o.PlaceholderStyle.ToLipgloss()
	styles.Blurred.Placeholder = o.PlaceholderStyle.ToLipgloss()
	i.SetStyles(styles)
	i.Placeholder = o.Placeholder
	i.SetWidth(o.Width)

	v := viewport.New(viewport.WithWidth(o.Width), viewport.WithHeight(o.Height))

	if len(o.Options) == 0 {
		if input, _ := stdin.Read(stdin.StripANSI(o.StripANSI)); input != "" {
			o.Options = strings.Split(input, o.InputDelimiter)
		} else {
			o.Options = files.List()
		}
	}

	if len(o.Options) == 0 {
		return errors.New("no options provided, see `gum filter --help`")
	}

	ctx, cancel := timeout.Context(o.Timeout)
	defer cancel()

	options := []tea.ProgramOption{
		tea.WithOutput(os.Stderr),
		tea.WithContext(ctx),
	}

	var matches []fuzzy.Match
	if o.Value != "" {
		i.SetValue(o.Value)
	}

	choices := map[string]string{}
	filteringChoices := []string{}
	for _, opt := range o.Options {

View on GitHub (pinned to 4d089f9550)

Solutions

1. Pipe non-empty input or pass options as arguments: gum filter a b c
2. Verify the upstream pipeline emits data before gum filter consumes it
3. If relying on file listing, run in a non-empty directory or pass --all/--hidden as appropriate

Example fix

// before
grep 'nomatch' file.txt | gum filter  # no options provided
// after
grep 'nomatch' file.txt | gum filter || echo 'no candidates'

candidates=$(grep pattern file.txt)
[ -n "$candidates" ] && printf '%s\n' "$candidates" | gum filter || echo 'no candidates to filter'

null

When it happens

Trigger: Options.Run() reaches `len(o.Options) == 0` — no options passed, empty stdin, and no filesystem fallback produced entries (e.g. empty directory).

Common situations: Piping output of a command that matched nothing (`grep foo file | gum filter` with no matches); running gum filter in an empty directory relying on file listing; quoting errors swallowing arguments.

Related errors

• no options provided, see `gum choose --help`
• nothing selected
• nothing selected
• invalid option format: %q
• unable to pick selection: %w

AI-assisted analysis of charmbracelet/gum@4d089f9550 (2026-08-31). Data as JSON: /api/errors/b111b1baa2959d3f. Report an issue: GitHub.