redis: AutoPipelineOptions.MaxBatchSize=%d must be >= 0

Error message

redis: AutoPipelineOptions.MaxBatchSize=%d must be >= 0

What it means

Returned by AutoPipelineOptions.Validate when MaxBatchSize is negative. Zero is allowed (meaning use the default batch size); negative values are rejected as typos rather than silently coerced. Validate runs lazily on the first AutoPipeline/AsyncAutoPipeline getter.

Source

Thrown at autopipeline.go:225

// error if MaxConcurrentBatches > 1 without Unordered: true — raising
// concurrency gives up command ordering, so the caller must opt in explicitly.
//
// Validate()==nil does not guarantee construction succeeds: rules that need
// the face (e.g. NumShards>1 requires Unordered on the deferred face) are
// enforced by the AutoPipeline/AsyncAutoPipeline getters. Note also that
// Options.AutoPipelineOptions is validated lazily — on the first getter
// call, not in NewClient.
func (cfg *AutoPipelineOptions) Validate() error {
	if cfg.MaxConcurrentBatches > 1 && !cfg.Unordered {
		return fmt.Errorf("redis: AutoPipelineOptions.MaxConcurrentBatches=%d requires Unordered:true "+
			"(parallel batches do not preserve command ordering); set Unordered:true to allow it, "+
			"or keep MaxConcurrentBatches=1 for an ordered stream", cfg.MaxConcurrentBatches)
	}
	// Reject obviously-wrong negatives so a typo surfaces at construction rather
	// than being silently coerced to a default. Zero is allowed and means "use
	// the default" (MaxBatchSize) or "no delay" (MaxFlushDelay).
	if cfg.MaxBatchSize < 0 {
		return fmt.Errorf("redis: AutoPipelineOptions.MaxBatchSize=%d must be >= 0", cfg.MaxBatchSize)
	}
	if cfg.MaxBatchBytes < 0 {
		return fmt.Errorf("redis: AutoPipelineOptions.MaxBatchBytes=%d must be >= 0", cfg.MaxBatchBytes)
	}
	if cfg.MaxConcurrentBatches < 0 {
		return fmt.Errorf("redis: AutoPipelineOptions.MaxConcurrentBatches=%d must be >= 0", cfg.MaxConcurrentBatches)
	}
	if cfg.MaxFlushDelay < 0 {
		return fmt.Errorf("redis: AutoPipelineOptions.MaxFlushDelay=%s must be >= 0", cfg.MaxFlushDelay)
	}
	if cfg.NumShards < 0 {
		return fmt.Errorf("redis: AutoPipelineOptions.NumShards=%d must be >= 0", cfg.NumShards)
	}
	if cfg.AdaptiveDelay && cfg.MaxFlushDelay <= 0 {
		return fmt.Errorf("redis: AutoPipelineOptions.AdaptiveDelay requires MaxFlushDelay > 0 " +
			"(adaptive delay scales MaxFlushDelay by queue fill; with no MaxFlushDelay it would " +
			"silently disable batch accumulation entirely)")
	}

View on GitHub (pinned to 36d97525cd)

Solutions

Set MaxBatchSize to 0 (use the default) or a positive integer.
If you intended 'no cap', use 0, not a negative number.
Validate config values at load time before passing to AutoPipelineOptions.

Example fix

// before
cfg := &redis.AutoPipelineOptions{MaxBatchSize: -1}
// cfg.Validate() => error

// after — 0 means use default, or set an explicit positive cap
cfg := &redis.AutoPipelineOptions{MaxBatchSize: 0}
// or
cfg := &redis.AutoPipelineOptions{MaxBatchSize: 500}

Defensive patterns

Strategy: validation

Validate before calling

func sanitizeBatchSize(n int) int {
    if n < 0 {
        return 0 // use default instead of an invalid negative
    }
    return n
}

Try / catch

if err := cfg.Validate(); err != nil {
    if strings.Contains(err.Error(), "MaxBatchSize") {
        cfg.MaxBatchSize = 0 // reset to default
    }
}

Prevention

Use 0 for 'use default' MaxBatchSize, never a negative.
Validate config values at load time before constructing AutoPipelineOptions.
Clamp parsed config values to >= 0.

When it happens

Trigger: Setting AutoPipelineOptions.MaxBatchSize to a negative number (e.g. -1 from an uninitialized/overflowing config value, or a sign error). Loading config where a missing value deserializes to a negative sentinel.

Common situations: Config parsing bugs that produce negatives. Arithmetic that underflows into a negative. Using -1 as an 'unlimited' sentinel when zero is the documented 'use default' value.

Related errors

AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06). Data as JSON: /data/errors/eda97e6046f46668.json. Report an issue: GitHub.