{"record":{"id":"d4efa3bf69920d46","repo":"kopia/kopia","slug":"s","errorCode":null,"errorMessage":"%s","messagePattern":"%s","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"repo/open.go","lineNumber":426,"sourceCode":"\n\treturn k, nil\n}\n\nfunc handleMissingRequiredFeatures(ctx context.Context, fmgr *format.Manager, ignoreErrors bool) error {\n\trequired, err := fmgr.RequiredFeatures(ctx)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"required features\")\n\t}\n\n\t// See if the current version of Kopia supports all features required by the repository format.\n\t// so we can safely fail to start in case repository has been upgraded to a new, incompatible version.\n\tif missingFeatures := feature.GetUnsupportedFeatures(required, supportedFeatures); len(missingFeatures) > 0 {\n\t\tfor _, mf := range missingFeatures {\n\t\t\tif ignoreErrors || mf.IfNotUnderstood.Warn {\n\t\t\t\tlog(ctx).Warnf(\"%s\", mf.UnsupportedMessage())\n\t\t\t} else {\n\t\t\t\t// by default, fail hard\n\t\t\t\treturn errors.Errorf(\"%s\", mf.UnsupportedMessage())\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc wrapLockingStorage(st blob.Storage, r format.BlobStorageConfiguration) blob.Storage {\n\t// collect prefixes that need to be locked on put\n\tprefixes := GetLockingStoragePrefixes()\n\n\treturn beforeop.NewWrapper(st, nil, nil, nil, func(_ context.Context, id blob.ID, opts *blob.PutOptions) error {\n\t\tfor _, prefix := range prefixes {\n\t\t\tif strings.HasPrefix(string(id), string(prefix)) {\n\t\t\t\topts.RetentionMode = r.RetentionMode\n\t\t\t\topts.RetentionPeriod = r.RetentionPeriod\n\n\t\t\t\tbreak","sourceCodeStart":408,"sourceCodeEnd":444,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/open.go#L408-L444","documentation":"By default, when the repository format requires features the current Kopia binary does not understand, open fails hard with errors.Errorf(\"%s\", mf.UnsupportedMessage()) — i.e. the message IS the underlying error. This guards against opening a repository that was upgraded by a newer, incompatible Kopia client. The message typically reads like 'repository requires feature X which is not supported'.","triggerScenarios":"Opening a repository whose format blob declares required features missing from supportedFeatures, while ignoreErrors is false and the missing feature has Warn=false (mf.IfNotUnderstood.Warn).","commonSituations":"Repository upgraded by a newer Kopia version, then accessed with an older client; repository created with experimental/new format features enabled; mixed-version kopia server and clients.","solutions":["Read the embedded UnsupportedMessage — it names the missing feature.","Upgrade the Kopia client to a version supporting the required feature and retry.","If you accept the risk, open with the ignoreMissingRequiredFeatures option (the error then becomes a warning log instead).","Avoid mixing Kopia client versions against the same repository."],"exampleFix":"// before: older client fails on upgraded repo\nrep, _ := repo.Open(ctx, configPath, \"pass\", opts)\n// after: upgrade client or explicitly ignore\nopts := repo.Options{IgnoreMissingRequiredFeatures: true}\nrep, _ := repo.Open(ctx, configPath, \"pass\", opts)","handlingStrategy":"validation","validationCode":"// Go: check client version is at least the repo's format version before opening\nif repoFormatVersion > supportedFormatVersion {\n    return fmt.Errorf(\"upgrade kopia client: repo requires format v%d, client supports v%d\", repoFormatVersion, supportedFormatVersion)\n}","typeGuard":null,"tryCatchPattern":"rep, err := repo.Open(ctx, cfg, pass, opts)\nif err != nil && strings.Contains(err.Error(), \"not supported\") {\n    // parse missing feature from message; upgrade client or opt into ignoring\n    return upgradeClientOrIgnore(err)\n}","preventionTips":["Upgrade all clients before any machine runs a newer Kopia version against the repository.","Check release notes for new required features before mixed-version deployments.","In automation, pin the Kopia version rather than using latest.","Use ignoreMissingRequiredFeatures only when you understand the named feature."],"tags":["kopia","version-compatibility","feature-flags","repository-open"],"backgroundTag":"feature-not-enabled","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"}