{"record":{"id":"ffa3cc79a4acfd54","repo":"vitessio/vitess","slug":"w-value-q","errorCode":null,"errorMessage":"%w value: %q","messagePattern":"%w value: %q","errorType":"validation","errorClass":"errUnsupportedDeCompressionEngine","httpStatus":null,"severity":"error","filePath":"go/vt/mysqlctl/builtinbackupengine.go","lineNumber":1587,"sourceCode":"\tdeCompressionEngine := bm.CompressionEngine\n\tif deCompressionEngine == \"\" {\n\t\tdeCompressionEngine = PgzipCompressor\n\t}\n\n\texternalDecompressorCmd := resolveExternalDecompressor(bm.ExternalDecompressor)\n\n\tvar decompressor io.ReadCloser\n\tvar err error\n\tif externalDecompressorCmd != \"\" {\n\t\tif deCompressionEngine == ExternalCompressor {\n\t\t\tdeCompressionEngine = externalDecompressorCmd\n\t\t\tdecompressor, err = newExternalDecompressor(ctx, deCompressionEngine, reader, params.Logger)\n\t\t} else {\n\t\t\tdecompressor, err = newBuiltinDecompressor(deCompressionEngine, reader, params.Logger)\n\t\t}\n\t} else {\n\t\tif deCompressionEngine == ExternalCompressor {\n\t\t\treturn nil, nil, fmt.Errorf(\"%w value: %q\", errUnsupportedDeCompressionEngine, ExternalCompressor)\n\t\t}\n\t\tdecompressor, err = newBuiltinDecompressor(deCompressionEngine, reader, params.Logger)\n\t}\n\tif err != nil {\n\t\treturn nil, nil, vterrors.Wrap(err, \"can't create decompressor\")\n\t}\n\n\tcloser := ioutil.NewTimeoutCloser(ctx, decompressor, closeTimeout)\n\tdecompressStats := params.Stats.Scope(stats.Operation(\"Decompressor:Read\"))\n\twrappedReader := ioutil.NewMeteredReader(decompressor, decompressStats.TimedIncrementBytes)\n\n\tcleanup := func() error {\n\t\tparams.Logger.Infof(\"closing decompressor for %s\", name)\n\t\tcloseAt := time.Now()\n\t\tcerr := closeWithRetry(ctx, params.Logger, closer, \"decompressor\")\n\t\tif cerr != nil {\n\t\t\tcerr = vterrors.Wrapf(cerr, \"failed to close decompressor %v\", name)\n\t\t\tparams.Logger.Error(cerr)","sourceCodeStart":1569,"sourceCodeEnd":1605,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/mysqlctl/builtinbackupengine.go#L1569-L1605","documentation":"When a backup was compressed with an external compression engine, restore tries newExternalDecompressor; but if the configured decompression engine is 'external' while the context does not provide one, this error is returned wrapping errUnsupportedDeCompressionEngine. It means Vitess was asked to decompress with an external tool that is not actually usable in this restore.","triggerScenarios":"RestoreFromBackup decompresses a backup file whose BackupManifest compressionEngine is ExternalCompressor, but no external decompressor command is configured/available in the restore params, so the code falls into the builtin branch and rejects ExternalCompressor there.","commonSituations":"Backup taken with --compression-engine=external but restore host lacks the external decompressor binary or the external_decompression command config; config lost between backup and restore hosts.","solutions":["Ensure the same external compression tool configured at backup time is installed on the restore host and on PATH.","Verify the external compressor/decompressor command configuration (externalcompression settings) is present on the tablet.","Or re-take the backup using a builtin engine (gzip, zstd, etc.) if you do not want the external dependency.","Confirm the backup manifest's CompressionEngine matches what the host can handle."],"exampleFix":"// before\n// backup taken with: --compression-engine external, restore host has no external decompressor\n// after\n// install the tool on the tablet host, or take backups with a builtin engine:\n// vtctldclient Backup --compression-engine zstd","handlingStrategy":"validation","validationCode":"// before restoring, confirm the host can handle the manifest's engine:\nif manifest.CompressionEngine == \"external\" {\n\t// check the external decompressor is configured/installed on this host\n\tif !externalDecompressionConfigured() {\n\t\treturn fmt.Errorf(\"backup uses external compression; tool not available\")\n\t}\n}","typeGuard":null,"tryCatchPattern":"decompressor, fileList, err := openDecompressor(...)\nif err != nil && errors.Is(err, errUnsupportedDeCompressionEngine) {\n\t// install/configure the external tool or re-take backup with builtin engine\n}","preventionTips":["Use the same compression engine and tooling on all tablet hosts.","Document required external binaries in deployment images.","Prefer builtin engines (gzip, zstd) unless external tooling is centrally managed."],"tags":["backup","compression","configuration"],"backgroundTag":"unsupported-compression-engine","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}