What causes "compression level must be between 1 and 9" in ipfs/kubo?

Set `--compression-level` to an integer between 1 and 9 (1=fastest, 9=best).

compression level must be between 1 and 9

Error message

compression level must be between 1 and 9

What it means

Kubo's `ipfs get` supports gzip compression of the output. When the `--compress` flag is set, `getCompressOptions` validates the `--compression-level` option and returns the exported sentinel `ErrInvalidCompressionLevel` if the value is not an integer between 1 and 9 (gzip levels). Omitting the level falls back to `gzip.DefaultCompression`, so the error only fires when an out-of-range level is explicitly supplied.

Source

Thrown at core/commands/get.go:25

	"errors"
	"fmt"
	"io"
	"os"
	gopath "path"
	"path/filepath"
	"strings"

	"github.com/ipfs/kubo/core/commands/cmdenv"
	"github.com/ipfs/kubo/core/commands/cmdutils"
	"github.com/ipfs/kubo/core/commands/e"

	"github.com/cheggaaa/pb/v3"
	"github.com/ipfs/boxo/files"
	"github.com/ipfs/boxo/tar"
	cmds "github.com/ipfs/go-ipfs-cmds"
)

var ErrInvalidCompressionLevel = errors.New("compression level must be between 1 and 9")

const (
	outputOptionName           = "output"
	archiveOptionName          = "archive"
	compressOptionName         = "compress"
	compressionLevelOptionName = "compression-level"
)

var GetCmd = &cmds.Command{
	Helptext: cmds.HelpText{
		Tagline: "Download IPFS objects.",
		ShortDescription: `
Stores to disk the data contained an IPFS or IPNS object(s) at the given path.

By default, the output will be stored at './<ipfs-path>', but an alternate
path can be specified with '--output=<path>' or '-o=<path>'.

To output a TAR archive instead of unpacked files, use '--archive' or '-a'.

View on GitHub (pinned to 329838acdf)

Solutions

Set `--compression-level` to an integer between 1 and 9 (1=fastest, 9=best).
Omit `--compression-level` entirely so gzip.DefaultCompression (-1/6) is used.
If you did not intend compression, drop the `--compress` flag and the level is not validated.

Example fix

// before
ipfs get QmXoypB... --compress --compression-level=0
// after
ipfs get QmXoypB... --compress --compression-level=6

Defensive patterns

Strategy: validation

Validate before calling

level, err := strconv.Atoi(levelStr)
if err != nil || level < 1 || level > 9 {
    return fmt.Errorf("compression level must be between 1 and 9, got %q", levelStr)
}

Type guard

func validGzipLevel(n int) bool { return n >= 1 && n <= 9 }

Try / catch

lvl, err := getCompressOptions(req)
if errors.Is(err, cmds.ErrInvalidCompressionLevel) { // sentinel comparison
    fmt.Fprintln(os.Stderr, "fix --compression-level: use 1..9 or omit it")
    return
}

Prevention

Omit --compression-level unless you need a specific trade-off; the default is gzip.DefaultCompression
Clamp or validate any user/script-supplied level before passing it: level = min(max(level,1),9)
Remember gzip range is 1..9 here; do not carry over 0-9 conventions from zstd or zlib defaults

When it happens

Trigger: Running `ipfs get <cid> --compress --compression-level=0`, `--compression-level=10`, a negative value, or any non-integer value that parses outside the 1..9 range (e.g. `--compression-level=100`). Only reached when `compress` is true; the level is ignored otherwise.

Common situations: Copy-pasted shell scripts with a level variable computed or defaulted to 0; confusing gzip levels (1-9) with other libraries' 0-9 ranges (where 0 means 'store'); passing a zstd-style level that exceeds 9.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/6d37614f4cdff8b0. Report an issue: GitHub.