What causes "unknown compression algorithm" in nats-io/nats-server?

Set compression to CompressionS2 (S2Compression) or CompressionNone (NoCompression) only

unknown compression algorithm

Error message

unknown compression algorithm

What it means

StoreCompression.MarshalJSON returns this error when serializing a compression algorithm value that is neither S2Compression nor NoCompression. The library only supports these two named algorithms for file-store stream compression, so an unknown value has no JSON representation.

Source

Thrown at server/filestore.go:138

	switch alg {
	case NoCompression:
		return "None"
	case S2Compression:
		return "S2"
	default:
		return "Unknown StoreCompression"
	}
}

func (alg StoreCompression) MarshalJSON() ([]byte, error) {
	var str string
	switch alg {
	case S2Compression:
		str = "s2"
	case NoCompression:
		str = "none"
	default:
		return nil, fmt.Errorf("unknown compression algorithm")
	}
	return json.Marshal(str)
}

func (alg *StoreCompression) UnmarshalJSON(b []byte) error {
	var str string
	if err := json.Unmarshal(b, &str); err != nil {
		return err
	}
	switch str {
	case "s2":
		*alg = S2Compression
	case "none":
		*alg = NoCompression
	default:
		return fmt.Errorf("unknown compression algorithm")
	}
	return nil

View on GitHub (pinned to 3a66a489d2)

Solutions

Set compression to CompressionS2 (S2Compression) or CompressionNone (NoCompression) only
Re-decode the config with a matching server version to populate valid enum values
Fix any integer casts that construct StoreCompression from raw numbers

Example fix

// before
alg := StoreCompression(7)
// after
alg := CompressionS2

Defensive patterns

Strategy: validation

Validate before calling

func validCompression(alg StoreCompression) bool {
    return alg == CompressionS2 || alg == CompressionNone
}

Type guard

func isKnownCompression(alg StoreCompression) bool {
    return alg == S2Compression || alg == NoCompression
}

Try / catch

b, err := json.Marshal(cfg)
if err != nil {
    if err.Error() == "unknown compression algorithm" {
        cfg.Compression = CompressionNone
        b, err = json.Marshal(cfg)
    }
    return err
}

Prevention

Only assign named constants (CompressionS2/CompressionNone), never raw ints
Keep server and client config-generation code on the same version
Round-trip marshal/unmarshal configs in tests

When it happens

Trigger: Marshaling a FileStoreConfig/StreamConfig whose StoreCompression field was set to an undefined or out-of-range value (e.g. constructed with an invalid cast like StoreCompression(7)).

Common situations: Deserializing a server config from a newer/older nats-server version that defined additional compression algorithms; hand-assembling config structs with raw integer constants.

Related errors

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