What causes "flag needs an argument: --%s" in JanDeDobbeleer/oh-my-posh?

Pass the value inline: use --flag=value or --flag value with the value present as the next token.

flag needs an argument: --%s

Error message

flag needs an argument: --%s

What it means

Raised by parseLong when a registered non-bool long flag is given without a value: not via '--flag=value', and no following token remains to consume as the value. The parser has nothing to pass to flag.Value.Set, so it errors. Bool flags are exempt because their bare presence implies true.

Source

Thrown at src/cmdflag/cmdflag.go:300

		// an unknown flag given as "--flag value" swallows the
		// value token unless the next token is itself a flag
		if !hasValue && len(rest) > 0 && !strings.HasPrefix(rest[0], "-") {
			return rest[1:], nil
		}

		return rest, nil
	}

	switch {
	case hasValue:
	case flag.Value.Type() == boolType:
		value = trueStr
	case len(rest) > 0:
		value = rest[0]
		rest = rest[1:]
	default:
		return rest, fmt.Errorf("flag needs an argument: --%s", name)
	}

	if err := flag.Value.Set(value); err != nil {
		return rest, fmt.Errorf("invalid argument %q for \"--%s\" flag: %v", value, flag.Name, err)
	}

	flag.Changed = true
	return rest, nil
}

func (f *FlagSet) parseShort(shorthands string, rest []string) ([]string, error) {
	for len(shorthands) > 0 {
		c := shorthands[0]

		flag := f.shorthands[c]
		if flag == nil {
			if f.ParseErrorsAllowlist.UnknownFlags {
				// drop the remainder of the group and a

View on GitHub (pinned to 0976794618)

Solutions

Pass the value inline: use --flag=value or --flag value with the value present as the next token.
Check shell quoting/expansion so an empty variable doesn't remove the value token.
If the flag should be optional-with-default, don't pass it at all; the registered default applies.
For bool-like toggles, register the flag as a bool so it can be used bare.

Example fix

// before
args := []string{"--config"} // flag needs an argument: --config
// after
args := []string{"--config", "~/.posh.toml"} // or "--config=$HOME/.posh.toml"

Defensive patterns

Strategy: validation

Validate before calling

func hasValueToken(args []string) error {
    for i, a := range args {
        if strings.HasPrefix(a, "--") && !strings.Contains(a, "=") {
            name := strings.TrimPrefix(a, "--")
            if isNonBoolFlag(flagSet, name) && i == len(args)-1 {
                return fmt.Errorf("flag --%s is missing its value", name)
            }
        }
    }
    return nil
}

Try / catch

if err := cmd.Execute(); err != nil {
    var msg string
    if fmt.Sprint(err) != "" && strings.HasPrefix(err.Error(), "flag needs an argument: ") {
        flagName := strings.TrimPrefix(err.Error(), "flag needs an argument: ")
        fmt.Fprintf(os.Stderr, "supply a value: ... %s=<value>\n", flagName)
        os.Exit(2)
    }
    _ = msg
    return err
}

Prevention

Quote shell variables: "--config ${CFG:-default.toml}" so empty vars never drop the token.
Prefer the --flag=value form; it fails only on a genuinely missing value.
Avoid building argv by string concatenation that can silently lose tokens.
Register toggles as bool flags so they never need values.

When it happens

Trigger: Calling Parse with a trailing '--name' where 'name' is a registered string/int/float flag and it is the last argument, e.g. Parse([]string{"--config"}).

Common situations: Shell variable expansion producing an empty value ("--config $EMPTY_VAR" collapses to "--config"); scripts accidentally dropping the value; users forgetting '=value' when they expected the equals form; quoting mistakes splitting the value into a separate consumed positional.

Related errors

AI-assisted analysis of JanDeDobbeleer/oh-my-posh@0976794618 (2026-08-31). Data as JSON: /api/errors/dff8b8b52eb4394b. Report an issue: GitHub.