What causes "limit %v exceeds maximum allowed value %v" in vitessio/vitess?

Lower the Limit to a value at or below maxBackupLimit

limit %v exceeds maximum allowed value %v

Error message

limit %v exceeds maximum allowed value %v

What it means

GetBackups supports truncating the returned backup list via req.Limit, but caps it at maxBackupLimit to prevent excessive work. If req.Limit is greater than maxBackupLimit, the request is rejected with this error before listing backup handles.

Source

Thrown at go/vt/vtctl/grpcvtctldserver/server.go:1552

	bs, err := backupstorage.GetBackupStorage()
	if err != nil {
		return nil, err
	}
	defer bs.Close()

	bucket := filepath.Join(req.Keyspace, req.Shard)
	span.Annotate("backup_path", bucket)

	bhs, err := bs.ListBackups(ctx, bucket)
	if err != nil {
		return nil, err
	}

	totalBackups := len(bhs)
	if req.Limit > 0 {
		if req.Limit > maxBackupLimit {
			return nil, fmt.Errorf("limit %v exceeds maximum allowed value %v", req.Limit, maxBackupLimit)
		}
		if int(req.Limit) < totalBackups {
			totalBackups = int(req.Limit)
		}
	}

	totalDetailedBackups := len(bhs)
	if req.DetailedLimit > 0 {
		if req.DetailedLimit > maxBackupLimit {
			return nil, fmt.Errorf("detailed_limit %v exceeds maximum allowed value %v", req.DetailedLimit, maxBackupLimit)
		}
		if int(req.DetailedLimit) < totalDetailedBackups {
			totalDetailedBackups = int(req.DetailedLimit)
		}
	}

	backups := make([]*mysqlctlpb.BackupInfo, 0, totalBackups)
	backupsToSkip := len(bhs) - totalBackups

View on GitHub (pinned to 01a25a7d17)

Solutions

Lower the Limit to a value at or below maxBackupLimit
Omit Limit (or set <= 0) to get the full untruncated list
Check the server constant maxBackupLimit in grpcvtctldserver for the allowed maximum

Example fix

// before
req.Limit = math.MaxInt32
// after
req.Limit = 1000

Defensive patterns

Strategy: validation

Validate before calling

const maxBackupLimit = 10000 // server-side cap
if req.Limit > 0 && req.Limit > maxBackupLimit {
    return fmt.Errorf("limit %d exceeds cap", req.Limit)
}

Try / catch

_, err := client.GetBackups(ctx, req)
if err != nil && strings.Contains(err.Error(), "limit %v exceeds maximum") {
    req.Limit = 0 // fetch untruncated
}

Prevention

Clamp client-side pagination to the documented server cap
Never use MaxInt sentinels for Limit
Omit Limit for full listings
Check maxBackupLimit in grpcvtctldserver when upgrading

When it happens

Trigger: Calling GetBackups with a Limit field exceeding the server-defined maxBackupLimit constant (e.g. requesting millions of backups in one call).

Common situations: Clients passing an unbounded or default-large page size from generic pagination code; misconfigured scripts that set Limit to a sentinel like MaxInt32.

Related errors

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