kopia/kopia · error

derive format encryption key

Error message

derive format encryption key

What it means

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.

Solutions

1. Upgrade Kopia to the latest version so the key derivation algorithm is recognized.
2. Verify the format blob's key derivation algorithm field is intact (compare against a backup of kopia.repository).
3. Reconnect to the repository (kopia repository connect) to refresh cached format metadata.
4. Restore the format blob from backup if derivation parameters are corrupted.

// preflight: confirm the client understands the format's key derivation algorithm
if knownKDFAlgs[formatBlob.KeyDerivationAlgorithm] == false {
    return errors.Errorf("unsupported KDF %q; upgrade kopia", formatBlob.KeyDerivationAlgorithm)
}

if err != nil && strings.Contains(err.Error(), "derive format encryption key") {
    // not a wrong password; a version/capability problem
    return errors.New("upgrade kopia client to a version supporting this repository format")
}

When it happens

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

Common situations: Opening a repository created by a newer Kopia version with an older client, corrupted format blob fields, or unusual custom format settings.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• unable to derive cache encryption key from password
• cannot derive cache HMAC secret
• decrypt
• derived key must be at least
• Failed to decrypt blob

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

Appendix: source

Thrown at repo/format/format_manager.go:149

		return errors.Wrap(err, "unable to read format blob")
	}

	j, err := ParseKopiaRepositoryJSON(b)
	if err != nil {
		return errors.Wrap(err, "can't parse format blob")
	}

	b, err = addFormatBlobChecksumAndLength(b)
	if err != nil {
		return errors.New("unable to add checksum")
	}

	// use old key, if present to avoid deriving it, which is expensive
	formatEncryptionKey := m.formatEncryptionKey
	if len(m.formatEncryptionKey) == 0 {
		formatEncryptionKey, err = j.DeriveFormatEncryptionKeyFromPassword(m.password)
		if err != nil {
			return errors.Wrap(err, "derive format encryption key")
		}
	}

	repoConfig, err := j.decryptRepositoryConfig(formatEncryptionKey)
	if err != nil {
		return ErrInvalidPassword
	}

	var blobCfg BlobStorageConfiguration

	if b2, _, err2 := m.readAndCacheRepositoryBlobBytes(ctx, KopiaBlobCfgBlobID); err2 == nil {
		var e2 error

		blobCfg, e2 = deserializeBlobCfgBytes(j, b2, formatEncryptionKey)
		if e2 != nil {
			return errors.Wrap(e2, "deserialize blob config")
		}
	} else if !errors.Is(err2, blob.ErrBlobNotFound) {

View on GitHub (pinned to 82495e54b5)