What causes "must be non-negative" in vitessio/vitess?

Pass a non-negative integer (0 or greater) for the flag

must be non-negative

Error message

must be non-negative

What it means

A flag registered with nonNegativeInt64Flag rejected a value because parsing succeeded but the integer is negative. vttablet's common flags only accept zero or positive int64 values for these options.

Source

Thrown at go/vt/vttablet/common/flags.go:50

	// VReplicationExperimentalFlags is a bitmask of experimental features in vreplication.
	VReplicationExperimentalFlagOptimizeInserts           = int64(1)
	VReplicationExperimentalFlagAllowNoBlobBinlogRowImage = int64(2)
	VReplicationExperimentalFlagVPlayerBatching           = int64(4)
)

type (
	nonNegativeInt64Flag struct {
		value *int64
	}
)

func (f nonNegativeInt64Flag) Set(v string) error {
	value, err := strconv.ParseInt(v, 10, 64)
	if err != nil {
		return err
	}
	if value < 0 {
		return errors.New("must be non-negative")
	}
	*f.value = value
	return nil
}

func (f nonNegativeInt64Flag) String() string {
	if f.value == nil {
		return "0"
	}
	return strconv.FormatInt(*f.value, 10)
}

func (f nonNegativeInt64Flag) Type() string {
	return "int"
}

var (
	vreplicationExperimentalFlags   = VReplicationExperimentalFlagOptimizeInserts | VReplicationExperimentalFlagAllowNoBlobBinlogRowImage | VReplicationExperimentalFlagVPlayerBatching

View on GitHub (pinned to 01a25a7d17)

Solutions

Pass a non-negative integer (0 or greater) for the flag
If you intended to disable the feature, use 0 or the dedicated disable flag instead of a negative value
Fix the config file/script generating the negative value

Example fix

// before
vttablet -heartbeat_interval=-5
// after
vttablet -heartbeat_interval=0

Defensive patterns

Strategy: validation

Validate before calling

v, err := strconv.ParseInt(flagValue, 10, 64)
if err != nil || v < 0 {
    return fmt.Errorf("flag %s must be a non-negative integer", flagName)
}

Prevention

Validate flag values in deploy scripts before launching vttablet
Never use negative numbers to 'disable' integer flags; use 0 or dedicated booleans
Lint config templates for negative numeric placeholders

When it happens

Trigger: Starting vttablet with a flag backed by nonNegativeInt64Flag set to a negative number (e.g. -heartbeat_interval=-1 or similar non-negative flags in go/vt/vttablet/common/flags.go).

Common situations: Config templates with placeholder negatives; operators trying to 'disable' a feature by passing -1 when the correct disable mechanism is different (0 or a boolean flag); automation generating flag values from subtraction.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/2d5d8337cacbd1c7. Report an issue: GitHub.