vitessio/vitess · error · errUnsupportedCompressionEngine

%w %q

Error message

%w %q

What it means

getExtensionFromEngine maps a compression engine name to its file extension(s) via engineExtensions. When the engine name is unknown to the registry, it returns errUnsupportedCompressionEngine wrapped with the offending engine name in quotes.

Source

Thrown at go/vt/mysqlctl/compression.go:92

}

func registerBackupCompressionFlags(fs *pflag.FlagSet) {
	fs.IntVar(&compressionLevel, "compression-level", compressionLevel, "what level to pass to the compressor.")
	fs.StringVar(&CompressionEngineName, "compression-engine-name", CompressionEngineName, "compressor engine used for compression.")
	fs.StringVar(&ExternalCompressorCmd, "external-compressor", ExternalCompressorCmd, "command with arguments to use when compressing a backup.")
	fs.StringVar(&ExternalCompressorExt, "external-compressor-extension", ExternalCompressorExt, "extension to use when using an external compressor.")
	fs.StringVar(&ExternalDecompressorCmd, "external-decompressor", ExternalDecompressorCmd, "command with arguments to use when decompressing a backup.")
	fs.BoolVar(&ExternalDecompressorUseManifest, "external-decompressor-use-manifest", ExternalDecompressorUseManifest, "allows the decompressor command stored in the backup manifest to be used at restore time. Enabling this is a security risk: an attacker with write access to the backup storage could modify the manifest to execute arbitrary commands on the tablet as the Vitess user. NOT RECOMMENDED.")
	fs.StringVar(&ManifestExternalDecompressorCmd, "manifest-external-decompressor", ManifestExternalDecompressorCmd, "command with arguments to store in the backup manifest when compressing a backup with an external compression engine.")
}

func getExtensionFromEngine(engine string) (string, error) {
	for ext, eng := range engineExtensions {
		if slices.Contains(eng, engine) {
			return ext, nil
		}
	}
	return "", fmt.Errorf("%w %q", errUnsupportedCompressionEngine, engine)
}

// resolveExternalDecompressor returns the external decompressor command to use
// at restore time. The CLI flag (--external-decompressor) takes precedence. The
// backup manifest value is only used when --external-decompressor-use-manifest
// is explicitly set to true.
func resolveExternalDecompressor(manifestDecompressor string) string {
	if ExternalDecompressorCmd != "" {
		return ExternalDecompressorCmd
	}
	if ExternalDecompressorUseManifest && manifestDecompressor != "" {
		return manifestDecompressor
	}
	return ""
}

// Validates if the external decompressor exists and return its path.
func validateExternalCmd(cmd string) (string, error) {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the engine name against supported values (e.g., gzip, zstd, lz4, snappy, pgzip, uncompressed, external).
2. If using an external compressor, set --external-compressor/--external-decompressor and use engine 'external'.
3. Confirm binary versions match the manifest (upgrade Vitess if the manifest uses a newer engine).
4. Trim whitespace/fix case in the engine configuration.

Example fix

// before
--compression-engine=gz
// after
--compression-engine=gzip

allowed := map[string]bool{"gzip":true,"pgzip":true,"zstd":true,"lz4":true,"snappy":true,"uncompressed":true,"external":true}
if !allowed[engineFlag] {
	return fmt.Errorf("unsupported engine %q", engineFlag)
}

if err != nil && errors.Is(err, compression.ErrUnsupportedCompressionEngine) {
	// correct the engine name or set external compressor flags
}

When it happens

Trigger: backupFileName (and backup/restore paths) configured with a --compression-engine / manifest engine value not in the registry (e.g., typo like 'gzip ' with whitespace, or an engine such as 'pgzip' spelled differently than supported).

Common situations: Typo in --compression-engine flag, manifest written by a newer Vitess with an engine unknown to an older binary, custom external compressor name passed where a built-in engine is expected.

Related errors

• %w value: %q
• %w value: %q
• --s3-backup-storage-bucket required
• cannot perform backup without my.cnf, please restart vttable
• error parsing the json file : %v

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/8e517b09d25e8f3b. Report an issue: GitHub.