urfave/cli · error

StopOnNthArg must be non-negative, got %d

Error message

StopOnNthArg must be non-negative, got %d

What it means

Before executing a command, run() validates that the StopOnNthArg option, when set, is not negative. A negative pointer value indicates a misconfiguration, so the command aborts early with 'StopOnNthArg must be non-negative, got %d'.

Source

Thrown at command_run.go:105

	return args, nil
}

// Run is the entry point to the command graph. The positional
// arguments are parsed according to the Flag and Command
// definitions and the matching Action functions are run.
func (cmd *Command) Run(ctx context.Context, osArgs []string) (deferErr error) {
	_, deferErr = cmd.run(ctx, osArgs)
	return deferErr
}

func (cmd *Command) run(ctx context.Context, osArgs []string) (_ context.Context, deferErr error) {
	tracef("running with arguments %[1]q (cmd=%[2]q)", osArgs, cmd.Name)
	cmd.setupDefaults(osArgs)

	// Validate StopOnNthArg
	if cmd.StopOnNthArg != nil && *cmd.StopOnNthArg < 0 {
		return ctx, fmt.Errorf("StopOnNthArg must be non-negative, got %d", *cmd.StopOnNthArg)
	}

	if v, ok := ctx.Value(commandContextKey).(*Command); ok {
		tracef("setting parent (cmd=%[1]q) command from context.Context value (cmd=%[2]q)", v.Name, cmd.Name)
		cmd.parent = v
	}

	if cmd.parent == nil {
		if cmd.ReadArgsFromStdin {
			if args, err := cmd.parseArgsFromStdin(); err != nil {
				return ctx, err
			} else {
				osArgs = append(osArgs, args...)
			}
		}
		// handle the completion flag separately from the flagset since
		// completion could be attempted after a flag, but before its value was put
		// on the command line. this causes the flagset to interpret the completion

View on GitHub (pinned to 1a4deb4f5a)

Solutions

1. Leave StopOnNthArg nil to disable it instead of pointing it at a negative number
2. Clamp or validate the value before assignment: if v < 0 { v = 0 } or skip assignment
3. Fix the config source (env/config file) that supplies the negative value

Example fix

// before
n := -1
cmd.StopOnNthArg = &n
// after
var n *int // nil disables the feature, or ensure *n >= 0 before assigning

func setStopOnNthArg(cmd *cli.Command, n int) error {
    if n < 0 { return fmt.Errorf("StopOnNthArg must be >= 0, got %d", n) }
    cmd.StopOnNthArg = &n
    return nil
}

func validStopOnNthArg(p *int) bool { return p == nil || *p >= 0 }

When it happens

Trigger: Setting cmd.StopOnNthArg to a pointer initialized from an unvalidated config/int that is negative (e.g. from a config file, env var, or default of -1 used as a sentinel while the code treats non-nil as active).

Common situations: Config-driven CLIs where -1 was meant to mean 'disabled' but was stored via pointer instead of leaving the pointer nil; arithmetic producing negative index; copy-pasted sentinel values.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

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

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