nats-io/nats-server · error

compression mode %q should have no more than 4 RTT threshold

Error message

compression mode %q should have no more than 4 RTT thresholds: %v

What it means

A compression mode's RTTThresholds list may contain at most 4 entries, corresponding to 'uncompressed', 'fast', 'better' and 'best' levels (with 0 entries allowed to skip levels). Providing more than 4 thresholds exceeds the defined compression levels, so Options validation rejects the configuration.

Source

Thrown at server/server.go:538

					}
				}
				rtts = append(rtts, n)
			}
			if len(rtts) > 0 {
				// Trim 0 that are at the end.
				stop := -1
				for i := len(rtts) - 1; i >= 0; i-- {
					if rtts[i] != 0 {
						stop = i
						break
					}
				}
				rtts = rtts[:stop+1]
			}
			if len(rtts) > 4 {
				// There should be at most values for "uncompressed", "fast",
				// "better" and "best" (when some 0 are present).
				return fmt.Errorf("compression mode %q should have no more than 4 RTT thresholds: %v", c.Mode, c.RTTThresholds)
			} else if len(rtts) == 0 {
				// But there should be at least 1 if the user provided the slice.
				// We would be here only if it was provided by say with values
				// being a single or all zeros.
				return fmt.Errorf("compression mode %q requires at least one RTT threshold", c.Mode)
			}
		}
		c.Mode = CompressionS2Auto
		c.RTTThresholds = rtts
	case "fast", "s2_fast":
		c.Mode = CompressionS2Fast
	case "better", "s2_better":
		c.Mode = CompressionS2Better
	case "best", "s2_best":
		c.Mode = CompressionS2Best
	default:
		return fmt.Errorf("unsupported compression mode %q", c.Mode)
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Trim RTTThresholds to at most 4 non-redundant entries
2. Map each entry to the documented levels: uncompressed, fast, better, best
3. Use 0 values to disable intermediate levels rather than adding more thresholds
4. Validate the config against the server's compression docs before rollout

Example fix

// before
c.RTTThresholds = []int64{5, 10, 20, 40, 80} // 5 entries
// after
c.RTTThresholds = []int64{10, 20, 40} // <= 4 entries

// Go: cap RTTThresholds length before applying Options
if n := countNonZero(cfg.RTTThresholds); n > 4 {
    return fmt.Errorf("at most 4 RTT thresholds allowed, got %d", n)
}

When it happens

Trigger: Setting Options.RTTThresholds with 5 or more entries for a compression mode, e.g. [10, 20, 30, 40, 50].

Common situations: Users extrapolating the threshold list thinking more granularity is supported, config generators producing per-node thresholds, or misunderstanding that zeros only mask levels rather than adding capacity.

Related errors

• RTT threshold values %v should be in ascending order
• failed to create mapping transform for stream import subject
• store operation not supported for URL Resolver
• delete must be enabled in server config
• Fetch timeout %v is too smal

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/931936219ec1bf49. Report an issue: GitHub.