kopia/kopia · critical

%s

Error message

%s

What it means

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'.

Solutions

1. Read the embedded UnsupportedMessage — it names the missing feature.
2. Upgrade the Kopia client to a version supporting the required feature and retry.
3. If you accept the risk, open with the ignoreMissingRequiredFeatures option (the error then becomes a warning log instead).
4. Avoid mixing Kopia client versions against the same repository.

Example fix

// before: older client fails on upgraded repo
rep, _ := repo.Open(ctx, configPath, "pass", opts)
// after: upgrade client or explicitly ignore
opts := repo.Options{IgnoreMissingRequiredFeatures: true}
rep, _ := repo.Open(ctx, configPath, "pass", opts)

// Go: check client version is at least the repo's format version before opening
if repoFormatVersion > supportedFormatVersion {
    return fmt.Errorf("upgrade kopia client: repo requires format v%d, client supports v%d", repoFormatVersion, supportedFormatVersion)
}

rep, err := repo.Open(ctx, cfg, pass, opts)
if err != nil && strings.Contains(err.Error(), "not supported") {
    // parse missing feature from message; upgrade client or opt into ignoring
    return upgradeClientOrIgnore(err)
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• derive format encryption key
• error opening content cache
• required features
• unable to create format manager
• unable to create shared content manager

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

Appendix: source

Thrown at repo/open.go:426

	return k, nil
}

func handleMissingRequiredFeatures(ctx context.Context, fmgr *format.Manager, ignoreErrors bool) error {
	required, err := fmgr.RequiredFeatures(ctx)
	if err != nil {
		return errors.Wrap(err, "required features")
	}

	// See if the current version of Kopia supports all features required by the repository format.
	// so we can safely fail to start in case repository has been upgraded to a new, incompatible version.
	if missingFeatures := feature.GetUnsupportedFeatures(required, supportedFeatures); len(missingFeatures) > 0 {
		for _, mf := range missingFeatures {
			if ignoreErrors || mf.IfNotUnderstood.Warn {
				log(ctx).Warnf("%s", mf.UnsupportedMessage())
			} else {
				// by default, fail hard
				return errors.Errorf("%s", mf.UnsupportedMessage())
			}
		}
	}

	return nil
}

func wrapLockingStorage(st blob.Storage, r format.BlobStorageConfiguration) blob.Storage {
	// collect prefixes that need to be locked on put
	prefixes := GetLockingStoragePrefixes()

	return beforeop.NewWrapper(st, nil, nil, nil, func(_ context.Context, id blob.ID, opts *blob.PutOptions) error {
		for _, prefix := range prefixes {
			if strings.HasPrefix(string(id), string(prefix)) {
				opts.RetentionMode = r.RetentionMode
				opts.RetentionPeriod = r.RetentionPeriod

				break

View on GitHub (pinned to 82495e54b5)