nats-io/nats-server · error

unsupported route compression mode %q

Error message

unsupported route compression mode %q

What it means

Route compression negotiation (processCompressionOption/selectedCompression helper in server.go): the remote peer advertised a compression mode this server does not recognize among the known S2 modes (uncompressed/fast/better/best/auto). Fired while setting up a route connection when the two servers disagree on supported compression identifiers — usually a version mismatch with a newer/older peer.

Source

Thrown at server/server.go:608

		return scm, nil
	case CompressionS2Auto, CompressionS2Uncompressed, CompressionS2Fast, CompressionS2Better, CompressionS2Best:
		// This case is here to make sure that if we don't recognize a
		// compression setting, we error out.
		if scm == CompressionAccept {
			// If our compression mode is "accept", then we will use the remote
			// compression mode, except if it is "auto", in which case we will
			// default to "fast". This is not a configuration (auto in one
			// side and accept in the other) that would be recommended.
			if rcm == CompressionS2Auto {
				return CompressionS2Fast, nil
			}
			// Use their compression mode.
			return rcm, nil
		}
		// Otherwise use our compression mode.
		return scm, nil
	default:
		return _EMPTY_, fmt.Errorf("unsupported route compression mode %q", rcm)
	}
}

// If the configured compression mode is "auto" then will return that,
// otherwise will return the given `cm` compression mode.
func compressionModeForInfoProtocol(co *CompressionOpts, cm string) string {
	if co.Mode == CompressionS2Auto {
		return CompressionS2Auto
	}
	return cm
}

// Given a connection RTT and a list of thresholds durations, this
// function will return an S2 compression level such as "uncompressed",
// "fast", "better" or "best". For instance, with the following slice:
// [5ms, 10ms, 15ms, 20ms], a RTT of up to 5ms will result
// in the compression level "uncompressed", ]5ms..10ms] will result in
// "fast" compression, etc..

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Upgrade both route peers to compatible nats-server versions
2. Disable compression on the route/cluster to avoid negotiation
3. Pin a commonly supported mode (e.g. fast) on both sides

When it happens

Trigger: Thrown at server/server.go:608 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/89a65f861c026f69. Report an issue: GitHub.