JanDeDobbeleer/oh-my-posh · error

unknown flag

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.

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"})
Defensive patterns

Strategy: validation

Validate before calling

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
}

Type guard

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

Try / catch

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
}

Prevention

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

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

Appendix: 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)