go-redis/redis · error

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

Error message

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

What it means

Returned by AutoPipelineOptions.Validate when NumShards is negative. Zero is allowed (meaning auto: a single shard for standalone, several slot-routed shards for cluster); negative values are rejected. NumShards controls how many independent queue+flusher shards the autopipeliner runs.

Source

Thrown at autopipeline.go:237

			"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)")
	}
	return nil
}

// cmdableClient is an interface for clients that support pipelining.
// Both Client and ClusterClient implement this interface. It embeds
// UniversalClient (Cmdable + Process + Do + AddHook + Watch + Subscribe... +
// Close + PoolStats) so the AutoPipeliner can delegate the non-batched surface
// back to the underlying client and itself satisfy UniversalClient.
type cmdableClient interface {
	UniversalClient
	// processPipelineHook is the hook-wrapped []Cmder pipeline entry — the same
	// method Pipeline.Exec is wired to (see Client.Pipeline). The flusher

View on GitHub (pinned to 36d97525cd)

Solutions

  1. Set NumShards to 0 (auto, the default) or a positive integer.
  2. Use 0 instead of a negative for 'auto'.
  3. Validate config values at load time.

Example fix

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

// after
cfg := &redis.AutoPipelineOptions{NumShards: 0} // auto
// or an explicit positive count (note: >1 on async face requires Unordered)
cfg := &redis.AutoPipelineOptions{NumShards: 4, Unordered: true}
Defensive patterns

Strategy: validation

Validate before calling

func sanitizeNumShards(n int) int {
    if n < 0 {
        return 0 // auto instead of an invalid negative
    }
    return n
}

Try / catch

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

Prevention

When it happens

Trigger: Setting AutoPipelineOptions.NumShards to a negative number. Config deserialization producing a negative from a missing/invalid field. Sign errors.

Common situations: Config parsing bugs that yield negatives. Using -1 as an 'auto' sentinel when zero is the documented auto value. Arithmetic underflow in computed shard counts.

Related errors

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