invalid --limit value (%d), maximum number of rows to compar

Error message

invalid --limit value (%d), maximum number of rows to compare needs to be greater than 0

What it means

VDiff validates the --limit flag (bound to maxRows) before starting a diff: rows-to-compare must be a positive integer. Non-positive values produce this explicit error naming the flag and the received value.

Source

Thrown at go/vt/vtctl/vdiff2.go:105

		if action != vdiff.CreateAction {
			return usage
		}
	case 3:
		action = vdiff.VDiffAction(strings.ToLower(subFlags.Arg(1)))
		actionArg = strings.ToLower(subFlags.Arg(2))
	default:
		return usage
	}
	if action == "" {
		return fmt.Errorf("invalid action '%s'; %s", subFlags.Arg(1), usage)
	}
	keyspace, workflowName, err := splitKeyspaceWorkflow(subFlags.Arg(0))
	if err != nil {
		return err
	}

	if *maxRows <= 0 {
		return fmt.Errorf("invalid --limit value (%d), maximum number of rows to compare needs to be greater than 0", *maxRows)
	}

	options := &tabletmanagerdatapb.VDiffOptions{
		PickerOptions: &tabletmanagerdatapb.VDiffPickerOptions{
			TabletTypes: *tabletTypes,
			SourceCell:  *sourceCell,
			TargetCell:  *targetCell,
		},
		CoreOptions: &tabletmanagerdatapb.VDiffCoreOptions{
			Tables:                *tables,
			AutoRetry:             *autoRetry,
			MaxRows:               *maxRows,
			Checksum:              *checksum,
			SamplePct:             *samplePct,
			TimeoutSeconds:        int64(timeout.Seconds()),
			MaxExtraRowsToCompare: *maxExtraRowsToCompare,
			UpdateTableStats:      *updateTableStats,
		},

View on GitHub (pinned to 01a25a7d17)

Solutions

Pass a positive integer, e.g. `--limit 10000`.
If you intended unlimited comparison, remove the --limit flag entirely rather than setting 0.
Fix the shell/script expression that computes the limit so it cannot yield 0 or negative values.
Verify the flag actually reached VDiff — flag types default to 0, so a misspelled flag name silently leaves maxRows at 0.

Example fix

// before
VDiff -- commerce.sell show all --limit 0
// after
VDiff -- commerce.sell show all --limit 100

Defensive patterns

Strategy: validation

Validate before calling

if limit <= 0 {
    return fmt.Errorf("--limit must be > 0 (got %d); omit the flag for unlimited", limit)
}

Try / catch

if err := runVDiff(args); err != nil {
    var se *vterrors.VitessError
    if strings.Contains(err.Error(), "invalid --limit value") {
        log.Warn("fix the computed limit before retrying", slog.Any("error", err))
    }
}

Prevention

Never use 0 to mean 'unlimited' — omit --limit instead.
When computing the limit in scripts, clamp: if v <= 0 { v = defaultLimit }.
Beware default 0 from a misspelled or unregistered flag.

When it happens

Trigger: Running `VDiff -- ks.wf <action> --limit 0` or `--limit -1` (or a value that flag parsing left at a non-positive default) so the `*maxRows <= 0` check fires.

Common situations: Script-generated commands where the limit is computed and can evaluate to 0 (empty result of a count query); confusing --limit semantics and setting it to 0 to mean 'unlimited' (it does not — omit or use a large positive value instead).

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/668c4b50d78fb8aa. Report an issue: GitHub.