What causes "max pack size too small, must be >= %v" in kopia/kopia?

Set MaxPackSize to a value >= minValidPackSize (use unit strings like 20MB).

max pack size too small, must be >=

Error message

max pack size too small, must be >= %v

What it means

MutableParameters.Validate enforces that MaxPackSize is at least minValidPackSize. A pack size below the minimum would break pack block internals (checksums, index offsets), so kopia refuses to accept such configuration. It is thrown when SetParameters is called with too-small MaxPackSize.

Solutions

Set MaxPackSize to a value >= minValidPackSize (use unit strings like 20MB).
Check the CLI flag value and units (`kopia repository set-parameters --max-pack-size=20MB`).
Query current parameters first (`kopia repository status`) and adjust incrementally.
Clamp the value in automation before calling SetParameters.

Example fix

// before
p.MaxPackSize = 1 * units.KiB
repo.SetParameters(ctx, p) // error: too small
// after
p.MaxPackSize = 20 * units.MiB
repo.SetParameters(ctx, p)

Defensive patterns

Strategy: validation

Validate before calling

if p.MaxPackSize < formatMinValidPackSize {
    return fmt.Errorf("MaxPackSize %v below minimum %v", p.MaxPackSize, formatMinValidPackSize)
}

Try / catch

if err := repo.SetParameters(ctx, p); err != nil {
    var verr interface{ Validation() bool }
    // treat as user input error, not retryable
    return fmt.Errorf("invalid parameters: %w", err)
}

Prevention

Always run MutableParameters.Validate() before SetParameters.
Use unit strings (20MB) in CLI flags to avoid unit mistakes.
Read `kopia repository status` for current valid ranges.

When it happens

Trigger: Calling SetParameters (or `kopia repository set-parameters --max-pack-size`) with a MaxPackSize smaller than the minimum valid pack size constant.

Common situations: Typo in CLI flag value (e.g. `--max-pack-size=1KB`); scripting parameter changes with wrong units; attempting to shrink pack size aggressively to save space.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/561d2b5c0f512b86. Report an issue: GitHub.

Appendix: source

Thrown at repo/format/content_format.go:75

// SupportsPasswordChange implements FormattingOptionsProvider.
func (f *ContentFormat) SupportsPasswordChange() bool {
	return f.EnablePasswordChange
}

// MutableParameters represents parameters of the content manager that can be mutated after the repository
// is created.
type MutableParameters struct {
	Version         Version          `json:"version,omitempty"`      // version number, must be "1", "2" or "3"
	MaxPackSize     int              `json:"maxPackSize,omitempty"`  // maximum size of a pack object
	IndexVersion    int              `json:"indexVersion,omitempty"` // force particular index format version (1,2,..)
	EpochParameters epoch.Parameters `json:"epochParameters"`        // epoch manager parameters
}

// Validate validates the parameters.
func (v *MutableParameters) Validate() error {
	if v.MaxPackSize < minValidPackSize {
		return errors.Errorf("max pack size too small, must be >= %v", units.BytesString(minValidPackSize))
	}

	if v.MaxPackSize > maxValidPackSize {
		return errors.Errorf("max pack size too big, must be <= %v", units.BytesString(maxValidPackSize))
	}

	if v.IndexVersion < 0 || v.IndexVersion > index.Version2 {
		return errors.New("invalid index version, supported versions are 1 & 2")
	}

	if err := v.EpochParameters.Validate(); err != nil {
		return errors.Wrap(err, "invalid epoch parameters")
	}

	return nil
}

// GetEncryptionAlgorithm implements encryption.Parameters.

View on GitHub (pinned to 82495e54b5)