dgraph-io/badger · error

cannot open DB because the external magic number doesn't mat

Error message

cannot open DB because the external magic number doesn't match, expected: %d, version present in manifest: %d

What it means

Returned by ReplayManifestFile when the external magic number stored in the MANIFEST header (bytes 4:6) does not equal the extMagic value the caller passed for this database flavor (e.g. a normal DB vs. an encryption/key-registry variant reading the same file). It means the MANIFEST on disk belongs to a different Badger variant or was written with an incompatible external identifier, so the file cannot be interpreted safely. Distinct from the internal version check: both version fields must match their expected constants.

Source

Thrown at manifest.go:377

	}
	if !bytes.Equal(magicBuf[0:4], magicText[:]) {
		return Manifest{}, 0, errBadMagic
	}

	extVersion := y.BytesToU16(magicBuf[4:6])
	version := y.BytesToU16(magicBuf[6:8])

	if version != badgerMagicVersion {
		return Manifest{}, 0,
			//nolint:lll
			fmt.Errorf("manifest has unsupported version: %d (we support %d).\n"+
				"Please see https://github.com/dgraph-io/badger/blob/main/docs/troubleshooting.md#i-see-manifest-has-unsupported-version-x-we-support-y-error"+
				" on how to fix this",
				version, badgerMagicVersion)
	}
	if extVersion != extMagic {
		return Manifest{}, 0,
			fmt.Errorf("cannot open DB because the external magic number doesn't match, "+
				"expected: %d, version present in manifest: %d", extMagic, extVersion)
	}

	stat, err := fp.Stat()
	if err != nil {
		return Manifest{}, 0, err
	}

	build := createManifest()
	var offset int64
	for {
		offset = r.count
		var lenCrcBuf [8]byte
		_, err := io.ReadFull(&r, lenCrcBuf[:])
		if err != nil {
			if err == io.EOF || err == io.ErrUnexpectedEOF {
				break
			}

View on GitHub (pinned to 2a001d466f)

Solutions

1. Confirm you are opening the database with the same Badger build/variant that created it (e.g. not mixing a tool built with different external magic constants)
2. Upgrade or pin the badger package to the exact version that produced the directory
3. If the directory was created by an incompatible tool, dump the data with that tool and re-import via a database created by the current binary
4. If the MANIFEST is simply corrupt (random ext bytes), restore it from backup or recreate the database

When it happens

Trigger: Thrown at manifest.go:377 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/e38197741d6bebca. Report an issue: GitHub.