{"record":{"id":"ab3a20552f5b1ce9","repo":"kopia/kopia","slug":"derive-format-encryption-key","errorCode":null,"errorMessage":"derive format encryption key","messagePattern":"derive format encryption key","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/format/format_manager.go","lineNumber":149,"sourceCode":"\t\treturn errors.Wrap(err, \"unable to read format blob\")\n\t}\n\n\tj, err := ParseKopiaRepositoryJSON(b)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"can't parse format blob\")\n\t}\n\n\tb, err = addFormatBlobChecksumAndLength(b)\n\tif err != nil {\n\t\treturn errors.New(\"unable to add checksum\")\n\t}\n\n\t// use old key, if present to avoid deriving it, which is expensive\n\tformatEncryptionKey := m.formatEncryptionKey\n\tif len(m.formatEncryptionKey) == 0 {\n\t\tformatEncryptionKey, err = j.DeriveFormatEncryptionKeyFromPassword(m.password)\n\t\tif err != nil {\n\t\t\treturn errors.Wrap(err, \"derive format encryption key\")\n\t\t}\n\t}\n\n\trepoConfig, err := j.decryptRepositoryConfig(formatEncryptionKey)\n\tif err != nil {\n\t\treturn ErrInvalidPassword\n\t}\n\n\tvar blobCfg BlobStorageConfiguration\n\n\tif b2, _, err2 := m.readAndCacheRepositoryBlobBytes(ctx, KopiaBlobCfgBlobID); err2 == nil {\n\t\tvar e2 error\n\n\t\tblobCfg, e2 = deserializeBlobCfgBytes(j, b2, formatEncryptionKey)\n\t\tif e2 != nil {\n\t\t\treturn errors.Wrap(e2, \"deserialize blob config\")\n\t\t}\n\t} else if !errors.Is(err2, blob.ErrBlobNotFound) {","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/format/format_manager.go#L131-L167","documentation":"When no cached format encryption key is available, refresh derives it from the stored password via j.DeriveFormatEncryptionKeyFromPassword. Failure here means the password-based key derivation (scrypt/PBKDF2 per the format's algorithm) could not run — typically an unsupported or unknown key-derivation algorithm in the format blob.","triggerScenarios":"DeriveFormatEncryptionKeyFromPassword returns an error because the format blob specifies a key derivation algorithm this Kopia build does not support, or derivation parameters (salt, cost) are corrupted/invalid.","commonSituations":"Opening a repository created by a newer Kopia version with an older client, corrupted format blob fields, or unusual custom format settings.","solutions":["Upgrade Kopia to the latest version so the key derivation algorithm is recognized.","Verify the format blob's key derivation algorithm field is intact (compare against a backup of kopia.repository).","Reconnect to the repository (kopia repository connect) to refresh cached format metadata.","Restore the format blob from backup if derivation parameters are corrupted."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// preflight: confirm the client understands the format's key derivation algorithm\nif knownKDFAlgs[formatBlob.KeyDerivationAlgorithm] == false {\n    return errors.Errorf(\"unsupported KDF %q; upgrade kopia\", formatBlob.KeyDerivationAlgorithm)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"derive format encryption key\") {\n    // not a wrong password; a version/capability problem\n    return errors.New(\"upgrade kopia client to a version supporting this repository format\")\n}","preventionTips":["Keep all clients accessing a repository on the same or newer Kopia version.","Check release notes for format changes before upgrading repositories.","Test opening repositories with a new client version before rolling it out fleet-wide."],"tags":["kopia","encryption","key-derivation","version-compatibility"],"backgroundTag":"unsupported-operation","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"}