What causes "flag needs an argument: %s" in urfave/cli?

Pass a value with the flag: --config=app.yml or --config app.yml

flag needs an argument: %s

Error message

flag needs an argument: %s

What it means

During parseFlags, a non-boolean flag was the last token on the command line (or consumed its only remaining arg), so no value was available to assign. The parser raises 'flag needs an argument: <name>'.

Source

Thrown at command_parse.go:180

				}
				tracef("parse Apply bool flag (fName=%[1]q) (fVal=%[2]q)", flagName, flagVal)
				if err := cmd.set(flagName, f, flagVal); err != nil {
					return &stringSliceArgs{posArgs}, err
				}
				continue
			}

			tracef("processing non bool flag (fName=%[1]q)", flagName)
			// not a bool flag so need to get the next arg
			if flagVal == "" && !valFromEqual {
				if len(rargs) == 1 {
					// In shell completion mode, preserve the flag so that DefaultCompleteWithFlags can use it
					// as lastArg and offer suggestions for it.
					if cmd.Root().shellCompletion {
						posArgs = append(posArgs, rargs...)
						return &stringSliceArgs{posArgs}, nil
					}
					return &stringSliceArgs{posArgs}, fmt.Errorf("%s%s", argumentNotProvidedErrMsg, firstArg)
				}
				flagVal = rargs[1]
				rargs = rargs[1:]
			}

			tracef("setting non bool flag (fName=%[1]q) (fVal=%[2]q)", flagName, flagVal)
			if err := cmd.set(flagName, f, flagVal); err != nil {
				return &stringSliceArgs{posArgs}, err
			}

			continue
		}

		// no flag lookup found and short handling is disabled
		if !shortOptionHandling {
			// In shell completion mode, preserve the partial flag so that DefaultCompleteWithFlags can use it
			// as lastArg and offer suggestions that match the prefix.
			if cmd.Root().shellCompletion {

View on GitHub (pinned to 1a4deb4f5a)

Solutions

Pass a value with the flag: --config=app.yml or --config app.yml
Check scripts for empty variable expansions that swallow the flag's argument
If the flag should work without a value, change it to a bool flag (BoolFlag) or give it a default via Destination/Value

Example fix

// before
$ app --config
// after
$ app --config=config.yml

Defensive patterns

Strategy: validation

Validate before calling

args := os.Args[1:]
for i, a := range args {
    if strings.HasPrefix(a, "--") && !strings.Contains(a, "=") && i == len(args)-1 {
        // flag with no trailing value
        fmt.Printf("flag %s requires a value\n", a)
    }
}

Try / catch

if err := cmd.Run(os.Args); err != nil {
    if strings.Contains(err.Error(), "flag needs an argument") {
        fmt.Fprintln(os.Stderr, "usage: app --config <path>")
        os.Exit(2)
    }
    return err
}

Prevention

Use --flag=value syntax in scripts to make values explicit
Quote variables so empty expansions still bind a value: "${CONFIG:-default}"
Give value flags defaults so omission is safe

When it happens

Trigger: Running a command where a value-taking flag appears last with no value, e.g. 'mycmd --output' or 'mycmd --config' with nothing after it; also when shell completion mode is off and the flag's value is missing.

Common situations: Shell scripts truncating trailing arguments; users forgetting a value after '=' style expectations; empty env-var expansion leaving '--flag ' with nothing following (e.g. mycmd --config $EMPTY).

Related errors

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