nats-io/nats-server · error

unsupported compression mode %q

Error message

unsupported compression mode %q

What it means

validateAndNormalizeCompressionOption did not recognize the configured compression mode string: it must be one of the accepted identifiers (auto, s2_auto, uncompressed, s2_uncompressed, fast, s2_fast, better, s2_better, best, s2_best, or accept where allowed). A typo or unsupported mode name in compression.mode (cluster/gateway/leaf contexts) triggers it at startup or reload.

Source

Thrown at server/server.go:555

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

// Returns `true` if the compression mode `m` indicates that the server
// will negotiate compression with the remote server, `false` otherwise.
// Note that the provided compression mode is assumed to have been
// normalized and validated.
func needsCompression(m string) bool {
	return m != _EMPTY_ && m != CompressionOff && m != CompressionNotSupported
}

// Compression is asymmetric, meaning that one side can have a different
// compression level than the other. However, we need to check for cases
// when this server `scm` or the remote `rcm` do not support compression
// (say older server, or test to make it behave as it is not), or have
// the compression off.
// Note that `scm` is assumed to not be "off" or "not supported".

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Correct the mode string, e.g. compression: { mode: fast }
2. Use the s2_-prefixed aliases exactly as documented
3. Check for stray quotes, spaces, or casing mistakes in the YAML value

When it happens

Trigger: Thrown at server/server.go:555 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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