vitessio/vitess · error

ErrRange

ErrRange

Error message

%w: backfill queue size must be non-negative; got %d

What it means

parseCacheConfigFlag validates the backfill-queue-size cluster config flag. After strconv.Atoi succeeds, a negative value is rejected and reported by wrapping strconv.ErrRange, so callers can errors.Is(err, strconv.ErrRange). This keeps cache backfill queue configuration within valid bounds.

Source

Thrown at go/vt/vtadmin/cluster/config.go:354

func parseCacheConfigFlag(cfg *cache.Config, name, val string) (err error) {
	switch name {
	case "default-expiration":
		cfg.DefaultExpiration, err = time.ParseDuration(val)
	case "cleanup-interval":
		cfg.CleanupInterval, err = time.ParseDuration(val)
	case "backfill-request-ttl":
		cfg.BackfillRequestTTL, err = time.ParseDuration(val)
	case "backfill-request-duplicate-interval":
		cfg.BackfillRequestDuplicateInterval, err = time.ParseDuration(val)
	case "backfill-queue-size":
		cfg.BackfillQueueSize, err = strconv.Atoi(val)
		if err != nil {
			return err
		}

		if cfg.BackfillQueueSize < 0 {
			return fmt.Errorf("%w: backfill queue size must be non-negative; got %d", strconv.ErrRange, cfg.BackfillQueueSize)
		}
	case "backfill-enqueue-wait-time":
		cfg.BackfillEnqueueWaitTime, err = time.ParseDuration(val)
	default:
		return errors.ErrNoFlag
	}

	return err
}

// RPCPoolConfig holds configuration options for creating RPCPools.
type RPCPoolConfig struct {
	Size        int           `json:"size"`
	WaitTimeout time.Duration `json:"wait_timeout"`
}

// NewRWPool returns an RPCPool from the given config that should be used for
// performing read-write operations. If the config is nil, or has a non-positive

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Set backfill-queue-size to a non-negative integer (0 disables backfill)
2. Check the cluster config file/flag source for an accidental '-' or unexpanded variable
3. If dynamic, clamp the value before applying config: max(0, n)

Example fix

// before (config flag)
--cluster-to-server --backfill-queue-size=-1
// after
--backfill-queue-size=100  // or 0 to disable

if n, err := strconv.Atoi(val); err != nil || n < 0 {
    return fmt.Errorf("backfill-queue-size must be a non-negative integer, got %q", val)
}

if err := cfg.Validate(); err != nil {
    if errors.Is(err, strconv.ErrRange) {
        // fix config before starting vtadmin
    }
}

When it happens

Trigger: Setting the vtadmin cluster config flag backfill-queue-size to a negative integer (e.g. backfill-queue-size=-1) via the cluster config file or the --cluster-cache flags parsed by parseOne.

Common situations: Copy-paste config mistakes with a leading minus sign; templated configs where a variable interpolates to a negative or '-' placeholder; misunderstanding that 0 (disable backfill) is the minimum valid value.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• unregistered Authenticator implementation
• malformed spec: doesn't define a range: %q
• conflicting entries: %q overlaps with %q
• failed to update throttler: %v err: %v
• fail to initialize Table ACL: %v

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