kopia/kopia · critical

Unsupported format version

Error message

Unsupported format version: %v

What it means

ResolveFormatVersion is called when loading a repository format blob; the format's Version field must be one of the known kopia repository format versions. If the parsed version number does not match any supported version (e.g. a future or corrupted version value), the default branch throws this error. It protects against opening repositories written by incompatible/newer kopia releases.

Solutions

1. Upgrade kopia to the version that created the repository (check `kopia --version` vs repo format version).
2. Inspect the kopia.repository format blob and verify the "version" field is a known value.
3. If the blob is corrupted, restore it from backup or use format-blob recovery (`kopia repository recover`).
4. Re-create the repository and re-sync data if no compatible version exists.

Example fix

// before
f := &repo.ContentFormat{Version: 3}
repo.ResolveFormatVersion(ctx, f) // panics with unsupported version
// after
f := &repo.ContentFormat{Version: 1} // use a version supported by this kopia build

supported := map[byte]bool{1: true, 2: true}
if !supported[f.Version] {
    return fmt.Errorf("kopia format version %d not supported by this build; upgrade kopia", f.Version)
}

func isSupportedFormatVersion(v int) bool { return v == 1 || v == 2 }

if _, err := repo.ResolveFormatVersion(ctx, f); err != nil {
    if strings.Contains(err.Error(), "Unsupported format version") {
        return fmt.Errorf("repository requires a newer kopia release: %w", err)
    }
    return err
}

When it happens

Trigger: Calling repositoryObjectFormatFromOptions/ResolveFormatVersion with a ContentFormat whose Version field is not a supported format version (typically a repository created by a newer kopia version, or a corrupted/fabricated kopia.repository blob).

Common situations: Upgrading kopia CLI downgraded to an older release then trying to open a newer repo; hand-edited or partially restored kopia.repository file; connecting to a repository whose format blob was produced by an incompatible tool.

Related errors

• derive format encryption key
• error creating format provider
• error getting mutable parameters
• repository format is up to date
• %s

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

Appendix: source

Thrown at repo/format/content_format.go:44

// ResolveFormatVersion applies format options parameters based on the format version.
func (f *ContentFormat) ResolveFormatVersion() error {
	switch f.Version {
	case FormatVersion2, FormatVersion3:
		f.EnablePasswordChange = true
		f.IndexVersion = index.Version2
		f.EpochParameters = epoch.DefaultParameters()

		return nil

	case FormatVersion1:
		f.EnablePasswordChange = false
		f.IndexVersion = index.Version1
		f.EpochParameters = epoch.Parameters{}

		return nil

	default:
		return errors.Errorf("Unsupported format version: %v", f.Version)
	}
}

// GetMutableParameters implements FormattingOptionsProvider.
func (f *ContentFormat) GetMutableParameters(_ context.Context) (MutableParameters, error) {
	return f.MutableParameters, nil
}

// GetCachedMutableParameters implements FormattingOptionsProvider.
func (f *ContentFormat) GetCachedMutableParameters() MutableParameters {
	return f.MutableParameters
}

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

View on GitHub (pinned to 82495e54b5)