What causes "Encryption key mismatch" in dgraph-io/badger?

Supply the original EncryptionKey option that the DB was created with

ErrEncryptionKeyMismatch

ErrEncryptionKeyMismatch

Error message

Encryption key mismatch

What it means

ErrEncryptionKeyMismatch is returned when the storage encryption key provided at Open does not match the key the DB was previously encrypted with. The key ID recorded in the key registry differs from the supplied key, so Badger refuses to open to prevent silent data corruption.

Source

Thrown at errors.go:101

	// ErrPlan9NotSupported is returned when opt.ReadOnly is used on Plan 9
	ErrPlan9NotSupported = stderrors.New("Read-only mode is not supported on Plan 9")

	// ErrTruncateNeeded is returned when the value log gets corrupt, and requires truncation of
	// corrupt data to allow Badger to run properly.
	ErrTruncateNeeded = stderrors.New(
		"Log truncate required to run DB. This might result in data loss")

	// ErrBlockedWrites is returned if the user called DropAll. During the process of dropping all
	// data from Badger, we stop accepting new writes, by returning this error.
	ErrBlockedWrites = stderrors.New("Writes are blocked, possibly due to DropAll or Close")

	// ErrNilCallback is returned when subscriber's callback is nil.
	ErrNilCallback = stderrors.New("Callback cannot be nil")

	// ErrEncryptionKeyMismatch is returned when the storage key is not
	// matched with the key previously given.
	ErrEncryptionKeyMismatch = stderrors.New("Encryption key mismatch")

	// ErrInvalidDataKeyID is returned if the datakey id is invalid.
	ErrInvalidDataKeyID = stderrors.New("Invalid datakey id")

	// ErrInvalidEncryptionKey is returned if length of encryption keys is invalid.
	ErrInvalidEncryptionKey = stderrors.New("Encryption key's length should be" +
		"either 16, 24, or 32 bytes")
	// ErrGCInMemoryMode is returned when db.RunValueLogGC is called in in-memory mode.
	ErrGCInMemoryMode = stderrors.New("Cannot run value log GC when DB is opened in InMemory mode")

	// ErrGCInReadOnlyMode is returned when db.RunValueLogGC is called in read-only mode.
	ErrGCInReadOnlyMode = stderrors.New("Cannot run value log GC when DB is opened in ReadOnly mode")

	// ErrDBClosed is returned when a get operation is performed after closing the DB.
	ErrDBClosed = stderrors.New("DB Closed")
)

View on GitHub (pinned to 2a001d466f)

Solutions

Supply the original EncryptionKey option that the DB was created with
Use the key registry rotation workflow (rotate proper key) instead of swapping keys directly in opts
Check the key source (env var, vault, config file) for typos or stale values
If the data is disposable, delete the DB directory and reopen with the new key

Example fix

// before
opts.EncryptionKey = []byte(newKey) // wrong key
_, err = badger.Open(opts) // ErrEncryptionKeyMismatch
// after
opts.EncryptionKey = originalKeyFromSecretStore
_, err = badger.Open(opts)

Defensive patterns

Strategy: validation

Validate before calling

key, err := loadEncryptionKey() // from vault/env
if err != nil { return err }
opts.EncryptionKey = key

Try / catch

db, err := badger.Open(opts)
if errors.Is(err, badger.ErrEncryptionKeyMismatch) {
    return fmt.Errorf("encryption key does not match this DB; check key source: %w", err)
}

Prevention

Store the DB encryption key durably (vault/KMS) and load the same one every run
Never edit the key value in config without a rotation procedure
Alert on env-var/config changes affecting the key before opening the DB
Test DB open in staging with the production key path

When it happens

Trigger: Opening a DB with opt.EncryptionKey different from the one used when it was created; rotating keys with doRotate/registry using an empty or wrong key list (rotate_test expects this error for nil/empty keys); switching between encrypted and plaintext modes.

Common situations: Deploy config pointing at a new/rotated KMS key; environment variable holding the key changed between runs; copying the DB directory to another environment without the original key; plaintext-to-encrypted transitions without proper rotation.

Related errors

AI-assisted analysis of dgraph-io/badger@2a001d466f (2026-09-05). Data as JSON: /api/errors/f1db448e2f975cfc. Report an issue: GitHub.