spf13/cobra · error

required flag(s) "%s" not set

Error message

required flag(s) "%s" not set

What it means

Returned by ValidateRequiredFlags when one or more flags marked required (via MarkFlagRequired / the BashCompOneRequiredFlag annotation) were not set on the command line. ValidateRequiredFlags runs during execute after flag parsing; it skips entirely if DisableFlagParsing is true. The message lists all missing required flag names joined by '", "'.

Source

Thrown at command.go:1198

func (c *Command) ValidateRequiredFlags() error {
	if c.DisableFlagParsing {
		return nil
	}

	flags := c.Flags()
	missingFlagNames := []string{}
	flags.VisitAll(func(pflag *flag.Flag) {
		requiredAnnotation, found := pflag.Annotations[BashCompOneRequiredFlag]
		if !found {
			return
		}
		if (requiredAnnotation[0] == "true") && !pflag.Changed {
			missingFlagNames = append(missingFlagNames, pflag.Name)
		}
	})

	if len(missingFlagNames) > 0 {
		return fmt.Errorf(`required flag(s) "%s" not set`, strings.Join(missingFlagNames, `", "`))
	}
	return nil
}

// checkCommandGroups checks if a command has been added to a group that does not exists.
// If so, we panic because it indicates a coding error that should be corrected.
func (c *Command) checkCommandGroups() {
	for _, sub := range c.commands {
		// if Group is not defined let the developer know right away
		if sub.GroupID != "" && !c.ContainsGroup(sub.GroupID) {
			panic(fmt.Sprintf("group id '%s' is not defined for subcommand '%s'", sub.GroupID, sub.CommandPath()))
		}

		sub.checkCommandGroups()
	}
}

// InitDefaultHelpFlag adds default help flag to c.

View on GitHub (pinned to adbc881390)

Solutions

1. Supply every flag named in the error (e.g. --config <value>).
2. If the requirement is conditional, remove MarkFlagRequired and use MarkFlagsRequiredTogether or custom validation in RunE.
3. Verify the flag name passed to MarkFlagRequired matches a defined flag (a typo here makes the flag impossible to satisfy).
4. If flag parsing is intentionally disabled, note that ValidateRequiredFlags is skipped — required-flag semantics won't apply.

Example fix

// before
cmd.Flags().String("config", "", "config path")
cmd.MarkFlagRequired("config")
// `cmd run` -> required flag(s) "config" not set

// after: `cmd run --config ./app.yaml`

// Verify required flags are satisfiable before shipping the command
func ensureRequiredFlagsDefined(cmd *cobra.Command) error {
    ok := true
    cmd.Flags().VisitAll(func(f *pflag.Flag) {
        if a, found := f.Annotations[cobra.BashCompOneRequiredFlag]; found && a[0] == "true" {
            // confirm the flag exists and is settable
            if cmd.Flags().Lookup(f.Name) == nil { ok = false }
        }
    })
    if !ok { return errors.New("required flag references undefined flag") }
    return nil
}

null

// In RunE, required flags are guaranteed present after ValidateRequiredFlags
RunE: func(cmd *cobra.Command, args []string) error {
    v, _ := cmd.Flags().GetString("config") // safe: marked required, validated upstream
    _ = v
    return nil
}

When it happens

Trigger: Calling cmd.MarkFlagRequired("config") and then invoking the command without --config. Also fires when a required flag is only set on a parent (persistent) but not merged, or when a required flag's name was typo'd in the MarkFlagRequired call so the user can never satisfy it.

Common situations: Forgetting a required flag at invocation, env-based config that was expected to set the flag but didn't, or a flag renamed in code while old docs/scripts still run.

Related errors

• if any flags in the group [%v] are set they must all be set;
• at least one of the flags in the group [%v] is required
• if any flags in the group [%v] are set none of the others ca
• unknown command %q for %q%s
• unknown command %q for %q

AI-assisted analysis of spf13/cobra@adbc881390 (2026-08-04). Data as JSON: /data/errors/378ebfa447a81dc6.json. Report an issue: GitHub.