{"record":{"id":"cb0219743c02aa9c","repo":"kopia/kopia","slug":"blob-configuration-cb0219","errorCode":null,"errorMessage":"blob configuration","messagePattern":"blob configuration","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/open.go","lineNumber":301,"sourceCode":"\tst, throttler, ferr := addThrottler(st, limits)\n\tif ferr != nil {\n\t\treturn nil, errors.Wrap(ferr, \"unable to add throttler\")\n\t}\n\n\tthrottler.OnUpdate(func(l throttling.Limits) error {\n\t\tlc2, err2 := LoadConfigFromFile(configFile)\n\t\tif err2 != nil {\n\t\t\treturn err2\n\t\t}\n\n\t\tlc2.Throttling = &l\n\n\t\treturn lc2.writeToFile(configFile)\n\t})\n\n\tblobcfg, err := fmgr.BlobCfgBlob(ctx)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"blob configuration\")\n\t}\n\n\tif blobcfg.IsRetentionEnabled() {\n\t\tst = wrapLockingStorage(st, blobcfg)\n\t}\n\n\t_, err = retry.WithExponentialBackoffMaxRetries(ctx, -1, \"wait for upgrade\", func() (any, error) {\n\t\tuli, err := fmgr.UpgradeLockIntent(ctx)\n\t\tif err != nil {\n\t\t\t//nolint:wrapcheck\n\t\t\treturn nil, err\n\t\t}\n\n\t\t// retry if upgrade lock has been taken\n\t\tif !cliOpts.PermissiveCacheLoading {\n\t\t\tif locked, _ := uli.IsLocked(cmOpts.TimeNow()); locked && options.UpgradeOwnerID != uli.OwnerID {\n\t\t\t\treturn nil, ErrRepositoryUnavailableDueToUpgradeInProgress\n\t\t\t}","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/open.go#L283-L319","documentation":"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\".","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry — if the cause is a transient storage error, a fresh open may succeed","Upgrade Kopia on the client to match/exceed the version that created the repository","Check the kopia.blobcfg blob in storage for integrity; restore from backup if corrupt","If retention is unused and the blob is unrecoverable, restore the repository format from a known-good backup"],"exampleFix":"// before: old client\n$ kopia repository connect s3 --...   # v0.10 client vs v0.14 repo\n// after\n$ brew upgrade kopia && kopia repository connect s3 --...","handlingStrategy":"retry","validationCode":"// ensure client version supports the repository format before opening\nv := kopiaClientVersion\nif v < minimumVersionForRepoFormat(repoFormatVersion) {\n    return fmt.Errorf(\"kopia client %v too old for repository format %v\", v, repoFormatVersion)\n}","typeGuard":null,"tryCatchPattern":"blobcfg, err := fmgr.BlobCfgBlob(ctx)\nif err != nil {\n    if isTransientStorageErr(err) {\n        time.Sleep(time.Second)\n        blobcfg, err = fmgr.BlobCfgBlob(ctx) // retry once\n    }\n    if err != nil {\n        return nil, fmt.Errorf(\"blob configuration unreadable (upgrade kopia client?): %w\", err)\n    }\n}","preventionTips":["Keep all Kopia clients on the same or newer version than the repository creator","Back up the repository format blobs (kopia.repository, kopia.blobcfg)","Upgrade clients before the repository format is upgraded"],"tags":["kopia","blobcfg","retention","format-blob"],"backgroundTag":"file-read-failed","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"}