kopia/kopia · error

blob configuration

Error message

blob configuration

What it means

fmgr.BlobCfgBlob failed to read or decrypt the blobcfg (retention) configuration from the repository format blob. This small JSON blob defines retention settings (e.g. S3 object-lock mode/period); an unreadable, corrupt, or undecryptable blobcfg makes it impossible to decide whether locking storage wrappers are needed, so open fails with the short message "blob configuration".

Solutions

1. Retry — if the cause is a transient storage error, a fresh open may succeed
2. Upgrade Kopia on the client to match/exceed the version that created the repository
3. Check the kopia.blobcfg blob in storage for integrity; restore from backup if corrupt
4. If retention is unused and the blob is unrecoverable, restore the repository format from a known-good backup

Example fix

// before: old client
$ kopia repository connect s3 --...   # v0.10 client vs v0.14 repo
// after
$ brew upgrade kopia && kopia repository connect s3 --...

// ensure client version supports the repository format before opening
v := kopiaClientVersion
if v < minimumVersionForRepoFormat(repoFormatVersion) {
    return fmt.Errorf("kopia client %v too old for repository format %v", v, repoFormatVersion)
}

blobcfg, err := fmgr.BlobCfgBlob(ctx)
if err != nil {
    if isTransientStorageErr(err) {
        time.Sleep(time.Second)
        blobcfg, err = fmgr.BlobCfgBlob(ctx) // retry once
    }
    if err != nil {
        return nil, fmt.Errorf("blob configuration unreadable (upgrade kopia client?): %w", err)
    }
}

When it happens

Trigger: openWithConfig calls fmgr.BlobCfgBlob(ctx) after creating the format manager; fails when the blobcfg part of the format blob is missing/corrupt, the unique ID/credentials needed to decrypt it are wrong, or storage IO for the format blob errors transiently.

Common situations: Repositories upgraded between Kopia versions where blobcfg format changed; storage backend truncating or corrupting the kopia.blobcfg blob; transient S3 errors; using a very old client against a newer repository format.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• can't parse format blob
• deserialize blob config
• error applying retention policy to
• format blob not found
• format blob too big

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

Appendix: source

Thrown at repo/open.go:301

	st, throttler, ferr := addThrottler(st, limits)
	if ferr != nil {
		return nil, errors.Wrap(ferr, "unable to add throttler")
	}

	throttler.OnUpdate(func(l throttling.Limits) error {
		lc2, err2 := LoadConfigFromFile(configFile)
		if err2 != nil {
			return err2
		}

		lc2.Throttling = &l

		return lc2.writeToFile(configFile)
	})

	blobcfg, err := fmgr.BlobCfgBlob(ctx)
	if err != nil {
		return nil, errors.Wrap(err, "blob configuration")
	}

	if blobcfg.IsRetentionEnabled() {
		st = wrapLockingStorage(st, blobcfg)
	}

	_, err = retry.WithExponentialBackoffMaxRetries(ctx, -1, "wait for upgrade", func() (any, error) {
		uli, err := fmgr.UpgradeLockIntent(ctx)
		if err != nil {
			//nolint:wrapcheck
			return nil, err
		}

		// retry if upgrade lock has been taken
		if !cliOpts.PermissiveCacheLoading {
			if locked, _ := uli.IsLocked(cmOpts.TimeNow()); locked && options.UpgradeOwnerID != uli.OwnerID {
				return nil, ErrRepositoryUnavailableDueToUpgradeInProgress
			}

View on GitHub (pinned to 82495e54b5)