urfave/cli · error

could not parse %[1]q as %[2]T value from %[3]s for flag %[4

Error message

could not parse %[1]q as %[2]T value from %[3]s for flag %[4]s: %[5]s

What it means

When a flag value arrives from an external source (env var, config file, etc.) during PostParse, the library calls flag.Set and wraps any failure in this message. It reports the raw value, the Go type of the flag's Value, where the value came from, the flag name, and the underlying parse error — e.g. parsing "abc" as an IntFlag from an env var fails.

Source

Thrown at flag_impl.go:144

}

// PostParse populates the flag given the flag set and environment
func (f *FlagBase[T, C, V]) PostParse() error {
	tracef("postparse (flag=%[1]q)", f.Name)

	if !f.hasBeenSet {
		if val, source, found := f.Sources.LookupWithSource(); found {
			// reflect.TypeOf yields nil when T is an interface type (e.g.
			// GenericFlag) and the value is nil, so the kind has to be
			// derived defensively.
			kind := reflect.Invalid
			if ty := reflect.TypeOf(f.Value); ty != nil {
				kind = ty.Kind()
			}

			if val != "" || kind == reflect.String {
				if err := f.Set(f.Name, val); err != nil {
					return fmt.Errorf(
						"could not parse %[1]q as %[2]T value from %[3]s for flag %[4]s: %[5]s",
						val, f.Value, source, f.Name, err,
					)
				}
			} else if val == "" && kind == reflect.Bool {
				_ = f.Set(f.Name, "false")
			}

			f.hasBeenSet = true
		}
	}

	return nil
}

// pass configuration of parsing to value
func (f *FlagBase[T, C, V]) setMultiValueParsingConfig(c multiValueParsingConfig) {
	tracef("setMultiValueParsingConfig %T, %+v", f.value, f.value)

View on GitHub (pinned to 1a4deb4f5a)

Solutions

  1. Read the wrapped %[5]s cause and fix the value at the cited source (%[3]s — the env var or file) to match the flag's type.
  2. For bool flags set from env, use exactly "true"/"false" (empty string is treated as "false"), not "yes"/"1 (string)" variants unsupported by strconv.ParseBool.
  3. Validate or sanitize env/config values before the app parses them, e.g. strip quotes/whitespace.
  4. Run with the offending env var unset to confirm the source is the culprit, then correct or remove it.

Example fix

// before
export TIMEOUT=10s\ 30s

// after
export TIMEOUT=30s
Defensive patterns

Strategy: validation

Validate before calling

// validate env-sourced values before running the command
case "$FLAG_TYPE" in
  bool) [[ "$MY_FLAG" =~ ^(true|false|1|0|t|f|T|F|TRUE|FALSE|True|False)$ ]] || { echo "MY_FLAG must be a bool" >&2; exit 1; } ;;
  int)  [[ "$MY_PORT" =~ ^-?[0-9]+$ ]] || { echo "MY_PORT must be an integer" >&2; exit 1; } ;;
esac

Type guard

func isParsableBool(s string) bool { _, err := strconv.ParseBool(strings.TrimSpace(s)); return err == nil }
func isParsableInt(s string) bool { _, err := strconv.Atoi(strings.TrimSpace(s)); return err == nil }

Try / catch

if err := cmd.Run(ctx, os.Args); err != nil {
    var msg string
    if strings.Contains(err.Error(), "could not parse") {
        fmt.Fprintf(os.Stderr, "fix the env/config value: %v\n", err)
        os.Exit(2)
    }
    _ = msg
    return err
}

Prevention

When it happens

Trigger: A flag's Sources (env var, file, config) yields a string that cannot be converted to the flag's type: non-numeric string into an Int/Float flag, invalid bool string like "yes" or "on" into a Bool flag (only "true"/"false"/"1"/"0" etc. are accepted), or malformed duration into a Duration flag.

Common situations: MY_FLAG=production where the flag is a bool; quoted values in env (MY_PORT="8080" with literal quotes on Windows); whitespace or typos in config files; version changes where a flag changed type from string to int.

Related errors

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