charmbracelet/gum · error

invalid option format: %q

Error message

invalid option format: %q

What it means

When a --label-delimiter is configured, each option string must split into exactly two parts (label and value) via strings.Cut. Any option that lacks the delimiter cannot be parsed and Run aborts with this error naming the offending option.

Source

Thrown at choose/command.go:44

	} else if len(o.Options) == 0 {
		if input == "" {
			return errors.New("no options provided, see `gum choose --help`")
		}
		o.Options = strings.Split(input, o.InputDelimiter)
	}

	// normalize options into a map
	options := map[string]string{}
	// keep the labels in the user-provided order
	var labels []string
	for _, opt := range o.Options {
		if o.LabelDelimiter == "" {
			options[opt] = opt
			continue
		}
		label, value, ok := strings.Cut(opt, o.LabelDelimiter)
		if !ok {
			return fmt.Errorf("invalid option format: %q", opt)
		}
		labels = append(labels, label)
		options[label] = value
	}
	if o.LabelDelimiter != "" {
		o.Options = labels
	}

	if o.SelectIfOne && len(o.Options) == 1 {
		fmt.Println(options[o.Options[0]])
		return nil
	}

	// We don't need to display prefixes if we are only picking one option.
	// Simply displaying the cursor is enough.
	if o.Limit == 1 && !o.NoLimit {
		o.SelectedPrefix = ""
		o.UnselectedPrefix = ""

View on GitHub (pinned to 4d089f9550)

Solutions

1. Ensure every option contains the label delimiter, e.g. gum choose --label-delimiter=: "name:1" "other:2"
2. Remove --label-delimiter if you don't need label/value pairs
3. Sanitize/validate the input list before piping or passing it to gum choose

Example fix

// before
gum choose --label-delimiter=: apple banana
// after
gum choose --label-delimiter=: "apple:1" "banana:2"

opts=("name:1" "other:2")
for opt in "${opts[@]}"; do
  [[ "$opt" == *:* ]] || { echo "bad option: $opt" >&2; exit 1; }
done
gum choose --label-delimiter=: "${opts[@]}"

null

null

When it happens

Trigger: Options.Run() iterates options with o.LabelDelimiter != "" and strings.Cut(opt, o.LabelDelimiter) returns ok=false — an option string does not contain the configured delimiter.

Common situations: Mixing labeled and unlabeled options (e.g. `gum choose --label-delimiter=: a b c:d`); copying option lists from an older gum version or another command that used a different delimiter; shell splitting dropping colons.

Related errors

• no options provided, see `gum choose --help`
• nothing selected
• unable to pick selection: %w
• at least one between --file and --directory must be set
• no file selected

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