dgraph-io/badger · error

ErrChecksumMismatch

ErrChecksumMismatch

Error message

checksum mismatch

What it means

ErrChecksumMismatch is a package-level sentinel in y meaning stored data did not match its recorded checksum. It is never returned bare: callers wrap it with context — key_registry.go wraps it when the DATAKEY file's CRC32C over the key-registry payload fails, and value.go wraps it when a value-log entry's checksum over key+value fails during a read of a value pointer. In both cases the underlying bytes on disk are corrupt (bit rot, torn write, wrong encryption key), and the wrap message names which structure failed.

Solutions

1. Inspect the wrapped message to identify the corrupted structure (DATAKEY registry vs. an individual value-log entry)
2. For a DATAKEY mismatch: verify you opened the database with the same encryption key; a wrong key almost always produces this error
3. For value corruption, run value-log GC and rely on Badger's truncation/recovery options to drop the damaged entry or file tail
4. Restore from backup if the affected data is critical, and check the disk for hardware errors

When it happens

Trigger: Thrown at y/checksum.go:18 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at y/checksum.go:18

/*
 * SPDX-FileCopyrightText: © 2017-2025 Istari Digital, Inc.
 * SPDX-License-Identifier: Apache-2.0
 */

package y

import (
	stderrors "errors"
	"hash/crc32"

	"github.com/cespare/xxhash/v2"

	"github.com/dgraph-io/badger/v4/pb"
)

// ErrChecksumMismatch is returned at checksum mismatch.
var ErrChecksumMismatch = stderrors.New("checksum mismatch")

// CalculateChecksum calculates checksum for data using ct checksum type.
func CalculateChecksum(data []byte, ct pb.Checksum_Algorithm) uint64 {
	switch ct {
	case pb.Checksum_CRC32C:
		return uint64(crc32.Checksum(data, CastagnoliCrcTable))
	case pb.Checksum_XXHash64:
		return xxhash.Sum64(data)
	default:
		panic("checksum type not supported")
	}
}

// VerifyChecksum validates the checksum for the data against the given expected checksum.
func VerifyChecksum(data []byte, expected *pb.Checksum) error {
	actual := CalculateChecksum(data, expected.Algo)
	if actual != expected.Sum {
		return Wrapf(ErrChecksumMismatch, "actual: %d, expected: %d", actual, expected.Sum)

View on GitHub (pinned to 2a001d466f)