min_ring_size value of %d is greater than max supported valu

Error message

min_ring_size value of %d is greater than max supported value %d for this field

What it means

Returned by ringhash.parseConfig (config.go:42-44) when MinRingSize exceeds ringHashSizeUpperBound (8*1024*1024 = 8M entries). The ring is an in-memory hash ring; an entry above 8M would consume excessive memory, so it is hard-capped. The %d values are the offending value and the 8M bound.

Source

Thrown at balancer/ringhash/config.go:43

	"google.golang.org/grpc/internal/envconfig"
	"google.golang.org/grpc/internal/metadata"
	iringhash "google.golang.org/grpc/internal/ringhash"
)

const (
	defaultMinSize         = 1024
	defaultMaxSize         = 4096
	ringHashSizeUpperBound = 8 * 1024 * 1024 // 8M
)

func parseConfig(c json.RawMessage) (*iringhash.LBConfig, error) {
	var cfg iringhash.LBConfig
	if err := json.Unmarshal(c, &cfg); err != nil {
		return nil, err
	}
	if cfg.MinRingSize > ringHashSizeUpperBound {
		return nil, fmt.Errorf("min_ring_size value of %d is greater than max supported value %d for this field", cfg.MinRingSize, ringHashSizeUpperBound)
	}
	if cfg.MaxRingSize > ringHashSizeUpperBound {
		return nil, fmt.Errorf("max_ring_size value of %d is greater than max supported value %d for this field", cfg.MaxRingSize, ringHashSizeUpperBound)
	}
	if cfg.MinRingSize == 0 {
		cfg.MinRingSize = defaultMinSize
	}
	if cfg.MaxRingSize == 0 {
		cfg.MaxRingSize = defaultMaxSize
	}
	if cfg.MinRingSize > cfg.MaxRingSize {
		return nil, fmt.Errorf("min %v is greater than max %v", cfg.MinRingSize, cfg.MaxRingSize)
	}
	if cfg.MinRingSize > envconfig.RingHashCap {
		cfg.MinRingSize = envconfig.RingHashCap
	}
	if cfg.MaxRingSize > envconfig.RingHashCap {
		cfg.MaxRingSize = envconfig.RingHashCap

View on GitHub (pinned to 03255a9237)

Solutions

Lower minRingSize to at most 8388608; for most workloads a value in the low thousands (default is 1024) gives good distribution.
If you genuinely need very large rings for consistency-hash fan-out, reconsider: ring size governs distribution quality, not throughput, and defaults are usually adequate.
If sourced from xDS, check the Cluster ring_hash_lb_config fields in the control plane.

Example fix

// before
raw := `{"minRingSize": 16777216, "maxRingSize": 16777216}` // > 8M -> error

// after
raw := `{"minRingSize": 1024, "maxRingSize": 4096}`

Defensive patterns

Strategy: validation

Validate before calling

const ringHashUpperBound = 8 * 1024 * 1024
func validateMinRingSize(raw []byte) error {
    var c struct{ MinRingSize uint64 `json:"minRingSize"` }
    _ = json.Unmarshal(raw, &c)
    if c.MinRingSize > ringHashUpperBound {
        return fmt.Errorf("minRingSize %d > %d", c.MinRingSize, ringHashUpperBound)
    }
    return nil
}

Prevention

Treat ring sizes as entry counts (small thousands), not bytes.
Prefer defaults (1024/4096) unless you have measured distribution needs.
Add a config lint that rejects ring sizes above 8M.

When it happens

Trigger: The ring_hash LB config sets minRingSize to a value greater than 8388608 (often from an xDS message or a service config with an overly large or misplaced magnitude, e.g. confusing entries with bytes).

Common situations: Translating a desired cache size in bytes into ring entries by mistake. xDS control plane pushing a huge value due to a unit error. Copying a config tuned for a different scale.

Related errors

AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07). Data as JSON: /api/errors/82d0010d01d897f7. Report an issue: GitHub.