kopia/kopia · error

error getting repository features

Error message

error getting repository features

What it means

During `kopia repository upgrade`, the upgrade command asks the repository's FormatManager for the set of required format features via RequiredFeatures(ctx). If that call fails, kopia wraps the underlying error with "error getting repository features" and aborts the upgrade before any parameters are modified. This error means kopia could not read or interpret the repository format metadata, so it cannot determine which format features the repository requires.

Solutions

1. Run `kopia repository status` to confirm the repository and format blob are readable before upgrading
2. Re-check the repository password / cached credentials and reconnect with `kopia repository connect`
3. Verify blob storage connectivity and credentials (bucket exists, permissions correct)
4. If the format blob is corrupted, restore it from the format-blob backup or contact support; do not hand-edit it
5. Retry the upgrade with a kopia version matching (or newer than) the one that created the repository

Example fix

// before: upgrading against a stale/broken connection
rep, _ := openRepo(ctx)
rf, err := rep.FormatManager().RequiredFeatures(ctx) // fails: blob unreachable
// after: validate repository access first
if err := rep.FormatManager().VerifyMasterPassword(ctx); err != nil {
    log(ctx).Errorf("repository unlock failed: %v", err)
    return err
}
rf, err := rep.FormatManager().RequiredFeatures(ctx)

// before upgrade, verify the repository format is readable
if _, err := rep.FormatManager().RequiredFeatures(ctx); err != nil {
    return fmt.Errorf("repository format unreadable, fix access/password first: %w", err)
}

// treat wrapped cause explicitly
var perr *blobStorageError
if errors.As(err, &perr) { /* fix storage access */ }
if passwordErr := rep.FormatManager().VerifyMasterPassword(ctx); passwordErr != nil { /* re-authenticate */ }

When it happens

Trigger: FormatManager().RequiredFeatures(ctx) returns an error — typically because the format-blob (kopia.repository) cannot be read/decrypted/decoded from blob storage, or the underlying blob storage API call fails.

Common situations: Corrupted or manually edited kopia.repository format blob; wrong repository password so format-blob decryption fails; blob storage backend unreachable or credentials expired mid-upgrade; upgrading a repository whose format blob was written by an incompatible kopia version.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• error finalizing upgrade
• error getting blob configuration
• error setting parameters
• blob configuration
• error deleting manifest

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

Appendix: source

Thrown at cli/command_repository_upgrade.go:447

			return errors.New("upgrade drain interrupted")
		}
	}

	return nil
}

// upgrade phase performs the actual upgrade action that upgrades the target
// repository. This phase runs after the lock has been acquired in one of the
// prior phases.
func (c *commandRepositoryUpgrade) upgrade(ctx context.Context, rep repo.DirectRepositoryWriter) error {
	mp, mperr := rep.ContentReader().ContentFormat().GetMutableParameters(ctx)
	if mperr != nil {
		return errors.Wrap(mperr, "mutable parameters")
	}

	rf, err := rep.FormatManager().RequiredFeatures(ctx)
	if err != nil {
		return errors.Wrap(err, "error getting repository features")
	}

	if mp.EpochParameters.Enabled {
		// nothing to upgrade on format, so let the next action commit the upgraded format blob
		return nil
	}

	mp.EpochParameters = epoch.DefaultParameters()
	mp.IndexVersion = 2

	log(ctx).Info("migrating current indices to epoch format")

	if uerr := rep.ContentManager().PrepareUpgradeToIndexBlobManagerV1(ctx); uerr != nil {
		return errors.Wrap(uerr, "error upgrading indices")
	}

	blobCfg, err := rep.FormatManager().BlobCfgBlob(ctx)
	if err != nil {

View on GitHub (pinned to 82495e54b5)