dgraph-io/badger · error

checksum type not supported

Error message

checksum type not supported

What it means

CalculateChecksum computes a checksum over data using the algorithm carried by a pb.Checksum. It only supports CRC32C (Castagnoli) and XXHash64; any other checksum algorithm value reaches the default branch and panics. This is a programming/config invariant violation, not a recoverable runtime condition.

Source

Thrown at y/checksum.go:28

	"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)
	}
	return nil
}

View on GitHub (pinned to 2a001d466f)

Solutions

1. Check that the checksum algorithm value comes from a compatible Badger version; rewrite the data with a supported algorithm (e.g. re-run badger stream/backup-restore with default checksum settings)
2. If constructing pb.Checksum manually, set Algo explicitly to pb.Checksum_CRC32C or pb.Checksum_XXHash64 before calling CalculateChecksum/VerifyChecksum
3. Verify data files are not corrupted; restore from backup if the Algo field is garbage
4. If wrapping calls, pre-check algo and handle unsupported values before calling

Example fix

// before
chk := &pb.Checksum{Sum: 123} // Algo unset -> panic
ok := VerifyChecksum(data, chk)
// after
chk := &pb.Checksum{Algo: pb.Checksum_CRC32C, Sum: 123}
ok := VerifyChecksum(data, chk)

func hasSupportedAlgo(c *pb.Checksum) bool {
	return c != nil && (c.Algo == pb.Checksum_CRC32C || c.Algo == pb.Checksum_XXHash64)
}
// call only if hasSupportedAlgo(chk)

func isSupportedChecksumAlgo(a pb.Checksum_Algorithm) bool {
	return a == pb.Checksum_CRC32C || a == pb.Checksum_XXHash64
}

// It panics, so guard the call:
func safeCalc(data []byte, algo pb.Checksum_Algorithm) (sum uint64, err error) {
	defer func() {
		if r := recover(); r != nil {
			err = fmt.Errorf("checksum: %v", r)
		}
	}()
	if !isSupportedChecksumAlgo(algo) {
		return 0, errors.New("unsupported checksum algo")
	}
	return CalculateChecksum(data, &pb.Checksum{Algo: algo}), nil
}

When it happens

Trigger: Calling CalculateChecksum (directly or via VerifyChecksum) with a pb.Checksum whose Algo is unset (0), a newer/older Badger checksum type, or any value outside {Checksum_CRC32C, Checksum_XXHash64}. VerifyChecksum on a manifest or table entry written by a different Badger version that introduced a new checksum algorithm.

Common situations: Upgrading/downgrading Badger so on-disk checksum algorithm IDs no longer match the compiled-in enum; hand-constructing a pb.Checksum{} without setting Algo (zero value); corrupted metadata changing the Algo field; fuzzing or generated test data with arbitrary algorithm values.

Related errors

• BlockCacheSize should be set since compression/encryption ar
• Cannot use GetSequence with managedDB=true.
• Cannot use GetSequence in read-only mode.
• Cannot flatten in read-only mode.
• Attempting to drop data in read-only mode.

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