{"record":{"id":"bab0211538e269fc","repo":"kopia/kopia","slug":"unsupported-format-version-v","errorCode":null,"errorMessage":"Unsupported format version: %v","messagePattern":"Unsupported format version: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"repo/format/content_format.go","lineNumber":44,"sourceCode":"// ResolveFormatVersion applies format options parameters based on the format version.\nfunc (f *ContentFormat) ResolveFormatVersion() error {\n\tswitch f.Version {\n\tcase FormatVersion2, FormatVersion3:\n\t\tf.EnablePasswordChange = true\n\t\tf.IndexVersion = index.Version2\n\t\tf.EpochParameters = epoch.DefaultParameters()\n\n\t\treturn nil\n\n\tcase FormatVersion1:\n\t\tf.EnablePasswordChange = false\n\t\tf.IndexVersion = index.Version1\n\t\tf.EpochParameters = epoch.Parameters{}\n\n\t\treturn nil\n\n\tdefault:\n\t\treturn errors.Errorf(\"Unsupported format version: %v\", f.Version)\n\t}\n}\n\n// GetMutableParameters implements FormattingOptionsProvider.\nfunc (f *ContentFormat) GetMutableParameters(_ context.Context) (MutableParameters, error) {\n\treturn f.MutableParameters, nil\n}\n\n// GetCachedMutableParameters implements FormattingOptionsProvider.\nfunc (f *ContentFormat) GetCachedMutableParameters() MutableParameters {\n\treturn f.MutableParameters\n}\n\n// SupportsPasswordChange implements FormattingOptionsProvider.\nfunc (f *ContentFormat) SupportsPasswordChange() bool {\n\treturn f.EnablePasswordChange\n}\n","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/format/content_format.go#L26-L62","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Upgrade kopia to the version that created the repository (check `kopia --version` vs repo format version).","Inspect the kopia.repository format blob and verify the \"version\" field is a known value.","If the blob is corrupted, restore it from backup or use format-blob recovery (`kopia repository recover`).","Re-create the repository and re-sync data if no compatible version exists."],"exampleFix":"// before\nf := &repo.ContentFormat{Version: 3}\nrepo.ResolveFormatVersion(ctx, f) // panics with unsupported version\n// after\nf := &repo.ContentFormat{Version: 1} // use a version supported by this kopia build","handlingStrategy":"validation","validationCode":"supported := map[byte]bool{1: true, 2: true}\nif !supported[f.Version] {\n    return fmt.Errorf(\"kopia format version %d not supported by this build; upgrade kopia\", f.Version)\n}","typeGuard":"func isSupportedFormatVersion(v int) bool { return v == 1 || v == 2 }","tryCatchPattern":"if _, err := repo.ResolveFormatVersion(ctx, f); err != nil {\n    if strings.Contains(err.Error(), \"Unsupported format version\") {\n        return fmt.Errorf(\"repository requires a newer kopia release: %w\", err)\n    }\n    return err\n}","preventionTips":["Pin kopia CLI/server versions to the release that created the repository.","Check format version in kopia.repository before connecting with older builds.","Keep format blob backups before upgrades."],"tags":["kopia","repository-format","version-compatibility"],"backgroundTag":"unsupported-config-value","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}