urfave/cli · error

invalid value %q for flag -%s: %v

Error message

invalid value %q for flag -%s: %v

What it means

Command.set invokes the flag's Set implementation and, on failure, wraps the error as fmt.Errorf("invalid value %q for flag -%s: %v", val, fName, err). This is the common wrapper for any flag value parse failure during command flag parsing (parseFlags), so the underlying cause (strconv errors, timestamp layouts, etc.) is nested in %v.

Source

Thrown at command.go:360

	newArgs := &stringSliceArgs{v: rawArgs}

	return newArgs
}

// Root returns the Command at the root of the graph
func (cmd *Command) Root() *Command {
	if cmd.parent == nil {
		return cmd
	}

	return cmd.parent.Root()
}

func (cmd *Command) set(fName string, f Flag, val string) error {
	cmd.setFlags[f] = struct{}{}
	cmd.setMultiValueParsingConfig(f)
	if err := f.Set(fName, val); err != nil {
		return fmt.Errorf("invalid value %q for flag -%s: %v", val, fName, err)
	}
	return nil
}

func (cmd *Command) lFlag(name string) Flag {
	for _, f := range cmd.allFlags() {
		if slices.Contains(f.Names(), name) {
			tracef("flag found for name %[1]q (cmd=%[2]q)", name, cmd.Name)
			return f
		}
	}
	return nil
}

func (cmd *Command) hasPersistentFlagOnAncestor(fl Flag) bool {
	for pCmd := cmd.parent; pCmd != nil; pCmd = pCmd.parent {
		for _, pFl := range pCmd.allFlags() {
			if pFl != fl {

View on GitHub (pinned to 1a4deb4f5a)

Solutions

1. Fix the value so it parses for the flag's type; read the trailing %v cause for the specific parse failure.
2. Run the command with --help to confirm each flag's expected value type.
3. In code that builds command lines programmatically, validate/serialize values before passing them.

Example fix

// before
myapp --port abc
// after
myapp --port 8080

// validate a known int flag before running
if v, ok := os.LookupEnv("MYAPP_PORT"); ok {
	if _, err := strconv.Atoi(v); err != nil {
		return fmt.Errorf("MYAPP_PORT must be an integer, got %q", v)
	}
}

if err := cmd.Run(ctx, os.Args); err != nil {
	var prefixed string
	if strings.HasPrefix(err.Error(), "invalid value \"") && strings.Contains(err.Error(), "for flag -") {
		fmt.Fprintf(os.Stderr, "bad flag value: %v\n", err)
		os.Exit(2)
	}
	_ = prefixed
	return err
}

When it happens

Trigger: Any command line where a flag receives a value its type cannot parse: --port abc for an IntFlag, --deadline not-a-date for a TimestampFlag, --debug maybe for a BoolFlag. parseFlags calls set for each flag occurrence.

Common situations: Typos in flag values, environment-driven defaults with bad content, scripts interpolating empty variables into flag values, or version upgrades changing accepted formats.

Related errors

• invalid value %q for argument %s: %v
• parse error
• got nil/empty layouts slice
• args %s has max 0, not parsing argument
• args %s has min[%d] > max[%d], not parsing argument

AI-assisted analysis of urfave/cli@1a4deb4f5a (2026-08-31). Data as JSON: /api/errors/82b4c32a5149065b. Report an issue: GitHub.