JanDeDobbeleer/oh-my-posh · error

unknown flag: --%s

Error message

unknown flag: --%s

What it means

This is the cmdflag parser's 'unknown long flag' error. When Parse encounters a token starting with '--', parseLong strips the '--' and looks the name up in the FlagSet's registered flags. If no flag with that name was registered via Var/StringVar/BoolVar etc., and the FlagSet's ParseErrorsAllowlist.UnknownFlags is false (the default), parsing stops with this error.

Source

Thrown at src/cmdflag/cmdflag.go:280

	}

	return nil
}

func (f *FlagSet) parseLong(name string, rest []string) ([]string, error) {
	value := ""
	hasValue := false

	if i := strings.Index(name, "="); i >= 0 {
		value = name[i+1:]
		name = name[:i]
		hasValue = true
	}

	flag := f.flags[name]
	if flag == nil {
		if !f.ParseErrorsAllowlist.UnknownFlags {
			return rest, fmt.Errorf("unknown flag: --%s", name)
		}

		// 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:]

View on GitHub (pinned to 0976794618)

Solutions

1. Fix the typo in the flag name on the command line (run the command with --help to list valid flags).
2. Register the flag on the FlagSet with Var/StringVar/IntVar/etc. before calling Parse if it should exist.
3. Set f.ParseErrorsAllowlist.UnknownFlags = true to silently ignore unknown flags instead of erroring.
4. Check the CLI version: if a script uses a flag removed in a newer oh-my-posh, update the script or pin the old version.

Example fix

// before
err := fs.Parse([]string{"--verbos", "x"}) // unknown flag: --verbos
// after
fs.BoolVarP(&verbose, "verbose", "v", false, "verbose output")
err := fs.Parse([]string{"--verbose", "x"})

func validateFlags(fs *cmdflag.FlagSet, args []string) error {
    for _, a := range args {
        if strings.HasPrefix(a, "--") {
            name := strings.TrimPrefix(strings.SplitN(a[2:], "=", 2)[0], "--")
            name = strings.SplitN(name, "=", 2)[0]
            if fs.Lookup(name) == nil {
                return fmt.Errorf("flag --%s is not registered; run with --help for valid flags", name)
            }
        }
    }
    return nil
}

func isRegisteredFlag(fs *cmdflag.FlagSet, long string) bool {
    return fs.Lookup(strings.TrimPrefix(long, "--")) != nil
}

if err := fs.Parse(args); err != nil {
    if strings.HasPrefix(err.Error(), "unknown flag: ") {
        fmt.Fprintln(os.Stderr, err, "\nRun with --help to see valid flags.")
        return errSilent // already reported; skip double handling
    }
    return err
}

When it happens

Trigger: Calling FlagSet.Parse (directly or via cmdtree Command.execute) with a '--name' or '--name=value' token whose name was never registered on the FlagSet or inherited persistent flag sets, while ParseErrorsAllowlist.UnknownFlags is false.

Common situations: Users typing a misspelled flag (e.g. --config vs --conf); scripts carrying flags from an older CLI version that was renamed or removed; passing flags intended for a subcommand at the parent level; a plugin/script forwarding flags the command does not declare.

Related errors

• flag needs an argument: --%s
• invalid argument %q for "--%s" flag: %v
• unknown shorthand flag: %q in -%s
• flag needs an argument: %q in -%s
• invalid argument %q for "-%s, --%s" flag: %v

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