What causes "can't duplicate this flag" in urfave/cli?

Remove the duplicate occurrence so the flag appears at most once on the command line.

can't duplicate this flag

Error message

can't duplicate this flag

What it means

flag_impl.go's Set enforces the OnlyOnce option: when a flag has OnlyOnce set to true and it is being applied for the second time (count == 1), it returns "can't duplicate this flag". Normally repeated flags accumulate (count-based values), but OnlyOnce forbids specifying the same flag more than once.

Source

Thrown at flag_impl.go:205

// Set applies given value from string
func (f *FlagBase[T, C, V]) Set(_ string, val string) error {
	tracef("apply (flag=%[1]q)", f.Name)

	// TODO move this phase into a separate flag initialization function
	// if flag has been applied previously then it would have already been set
	// from env or file. So no need to apply the env set again. However
	// lots of units tests prior to persistent flags assumed that the
	// flag can be applied to different flag sets multiple times while still
	// keeping the env set.
	if !f.applied {
		if err := f.PreParse(); err != nil {
			return err
		}
		f.applied = true
	}

	if f.count == 1 && f.OnlyOnce {
		return fmt.Errorf("can't duplicate this flag")
	}

	f.count++
	if err := f.value.Set(val); err != nil {
		return err
	}
	f.hasBeenSet = true
	if f.Validator != nil {
		if err := f.Validator(f.value.Get().(T)); err != nil {
			return err
		}
	}
	return nil
}

func (f *FlagBase[T, C, V]) Get() any {
	if f.value != nil {
		return f.value.Get()

View on GitHub (pinned to 1a4deb4f5a)

Solutions

Remove the duplicate occurrence so the flag appears at most once on the command line.
If repetition is intended, set OnlyOnce: false (the default) on the flag definition so subsequent Set calls accumulate instead of erroring.
Deduplicate flags in generating scripts (e.g. use arrays + sort -u before joining into a command line).
Check Sources/env to ensure the flag is not being set from two places when OnlyOnce is enabled.

Example fix

// flag definition
&cli.StringFlag{Name: "tag", OnlyOnce: true}
// before
myapp --tag a --tag b
// after
myapp --tag a   # or set OnlyOnce: false to allow repeats

Defensive patterns

Strategy: validation

Validate before calling

// dedupe repeated flags before invoking
args=("$@")
mapfile -t deduped < <(printf '%s\n' "${args[@]}" | awk '!seen[$0]++')
# pass "${deduped[@]}" to the command when OnlyOnce flags are in play

Try / catch

if err := cmd.Run(ctx, os.Args); err != nil {
    if strings.Contains(err.Error(), "can't duplicate this flag") {
        fmt.Fprintln(os.Stderr, "this flag may only be specified once")
        os.Exit(2)
    }
    return err
}

Prevention

Pass OnlyOnce flags at most once per command line.
Set OnlyOnce: false (omit it) if the flag should be repeatable.
Deduplicate flags in scripts that build command lines dynamically.
Avoid supplying the same flag from both env Sources and CLI when OnlyOnce is enabled.

When it happens

Trigger: A flag created with OnlyOnce: true is supplied two or more times, e.g. `myapp --tag a --tag b`, or the flag is set once from an external source and again on the command line so Set runs a second time.

Common situations: Users used to repeatable flags (like docker -v) applying them to a flag marked OnlyOnce; scripts that append flags in a loop without deduplication; env var + CLI argument both supplying the same OnlyOnce flag.

Related errors

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